From 12394c2ad5f31be0aa0ed2d5e3c3f1aeb8a5a60d Mon Sep 17 00:00:00 2001
From: Kenton Duprey <kenton@clerk.dev>
Date: Wed, 20 Aug 2025 14:07:51 -0400
Subject: [PATCH] fix(clerk-js): Add a development warning when missing both
 custom router options

Signed-off-by: Kenton Duprey <kenton@clerk.dev>
---
 .changeset/true-mirrors-check.md          |  5 +++++
 packages/clerk-js/bundlewatch.config.json |  2 +-
 packages/clerk-js/src/core/clerk.ts       | 15 +++++++++++++++
 3 files changed, 21 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/true-mirrors-check.md

diff --git a/.changeset/true-mirrors-check.md b/.changeset/true-mirrors-check.md
new file mode 100644
index 00000000000..597d1b49ecd
--- /dev/null
+++ b/.changeset/true-mirrors-check.md
@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Add a development-mode warning when exactly one of `routerPush` or `routerReplace` is provided in `ClerkOptions`. Both must be defined together for custom router navigation to work correctly.
\ No newline at end of file
diff --git a/packages/clerk-js/bundlewatch.config.json b/packages/clerk-js/bundlewatch.config.json
index 547117e0782..271d9cd5159 100644
--- a/packages/clerk-js/bundlewatch.config.json
+++ b/packages/clerk-js/bundlewatch.config.json
@@ -1,6 +1,6 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "626KB" },
+    { "path": "./dist/clerk.js", "maxSize": "626.1KB" },
     { "path": "./dist/clerk.browser.js", "maxSize": "78KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "119KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "61KB" },
diff --git a/packages/clerk-js/src/core/clerk.ts b/packages/clerk-js/src/core/clerk.ts
index ac78f078b6b..a80d8f98b95 100644
--- a/packages/clerk-js/src/core/clerk.ts
+++ b/packages/clerk-js/src/core/clerk.ts
@@ -428,6 +428,21 @@ export class Clerk implements ClerkInterface {
 
     this.#options = this.#initOptions(options);
 
+    // In development mode, if custom router options are provided, warn if both routerPush and routerReplace are not provided
+    if (
+      this.#instanceType === 'development' &&
+      (this.#options.routerPush || this.#options.routerReplace) &&
+      (!this.#options.routerPush || !this.#options.routerReplace)
+    ) {
+      // Typing this.#options as ClerkOptions to ensure proper type checking. TypeScript will infer the type as `never`
+      // since missing both `routerPush` and `routerReplace` is not a valid ClerkOptions.
+      const options = this.#options as ClerkOptions;
+      const missingRouter = !options.routerPush ? 'routerPush' : 'routerReplace';
+      logger.warnOnce(
+        `Clerk: Both \`routerPush\` and \`routerReplace\` need to be defined, but \`${missingRouter}\` is not defined. This may cause issues with navigation in your application.`,
+      );
+    }
+
     /**
      * Listen to `Session.getToken` resolving to emit the updated session
      * with the new token to the state listeners.