fix(init): scaffold ssr.noExternal for React Router v8 projects

.changeset/react-router-v8-noexternal.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+Fix `clerk init` for React Router v8 projects by adding `@clerk/react-router` to `ssr.noExternal` in the Vite config, preventing dev-mode SSR from failing with "useNavigate() may be used only in the context of a <Router>".

packages/cli-core/src/commands/init/frameworks/react-router.test.ts

@@ -434,3 +434,118 @@ export default [index("routes/home.tsx")] satisfies RouteConfig;
  'route("($locale)/sign-up/*", "routes/($locale).sign-up.tsx")',
  );
 });
+
+test("adds ssr.noExternal to vite.config.ts for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [reactRouter()],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("noExternal");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("appends to an existing ssr.noExternal array for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["some-other-pkg"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("some-other-pkg");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("skips vite config when @clerk/react-router is already in ssr.noExternal", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["@clerk/react-router"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("skip");
+});
+
+test("does not touch vite config for React Router 7", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "7.9.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).not.toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is missing on React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is a function form", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig(({ command }) => ({
+ plugins: [],
+}));
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});

packages/cli-core/src/commands/init/frameworks/react-router.ts

@@ -382,6 +382,83 @@ function scaffoldConfig(ctx: ProjectContext): Promise<FileAction | null> {
  });
 }
 
+type ViteScaffoldResult = {
+ action: FileAction | null;
+ /** True when the noExternal entry is needed but couldn't be applied — user must wire manually. */
+ needsManualViteWire: boolean;
+};
+
+/**
+ * Add `ssr.noExternal: ["@clerk/react-router"]` to the vite config.
+ * React Router v8 ships development/production conditional exports; `react-router dev`
+ * externalizes @clerk/react-router for SSR, so it resolves react-router's production
+ * build while app code gets the development build — two Router contexts, and every
+ * SSR render throws "useNavigate() may be used only in the context of a <Router>".
+ * https://github.com/remix-run/react-router/issues/15232
+ */
+function addClerkNoExternal(content: string): string {
+ try {
+ const mod = parseModule(content);
+ const defaultExport = mod.exports.default;
+ if (!defaultExport || typeof defaultExport !== "object") return content;
+
+ // `export default defineConfig({...})` proxies the call expression; property writes on it
+ // throw, so operate on the call's first argument (the config object) instead.
+ const config = defaultExport.$type === "function-call" ? defaultExport.$args[0] : defaultExport;
+ if (!config || typeof config !== "object") return content;
+
+ if (!config.ssr) config.ssr = {};
+ if (config.ssr.noExternal === undefined) config.ssr.noExternal = [];
+ // boolean/string/regex noExternal: leave it and let the caller emit the manual instruction
+ if (!Array.isArray(config.ssr.noExternal)) return content;
+
+ if (!config.ssr.noExternal.includes("@clerk/react-router")) {
+ config.ssr.noExternal.push("@clerk/react-router");
+ }
+ return mod.generate().code;
+ } catch {
+ return content;
+ }
+}
+
+async function scaffoldViteConfig(ctx: ProjectContext): Promise<ViteScaffoldResult> {
+ // The dual-instance issue only exists in v8's conditional exports; v7 doesn't need this.
+ if (shouldEnableV8MiddlewareFlag(ctx)) return { action: null, needsManualViteWire: false };
+
+ const configPath = await findFirstFile(ctx.cwd, [
+ "vite.config.ts",
+ "vite.config.js",
+ "vite.config.mts",
+ "vite.config.mjs",
+ ]);
+ if (!configPath) return { action: null, needsManualViteWire: true };
+
+ const content = await Bun.file(join(ctx.cwd, configPath)).text();
+ if (content.includes("@clerk/react-router")) {
+ return {
+ action: {
+ type: "skip",
+ path: configPath,
+ skipReason: "Already references @clerk/react-router in vite config",
+ },
+ needsManualViteWire: false,
+ };
+ }
+
+ const updated = addClerkNoExternal(content);
+ if (updated === content) return { action: null, needsManualViteWire: true };
+
+ return {
+ action: {
+ path: configPath,
+ type: "modify",
+ content: updated,
+ description: "Add @clerk/react-router to ssr.noExternal (React Router v8 dev SSR fix)",
+ },
+ needsManualViteWire: false,
+ };
+}
+
 export const reactRouter: FrameworkScaffold = {
  name: "React Router",
  dep: "react-router",
@@ -390,8 +467,9 @@ export const reactRouter: FrameworkScaffold = {
  matches: (ctx) => ctx.framework.dep === "react-router",
 
  async scaffold(ctx: ProjectContext): Promise<ScaffoldPlan> {
- const [configAction, rootResult, localePrefix, envAction] = await Promise.all([
+ const [configAction, viteResult, rootResult, localePrefix, envAction] = await Promise.all([
  scaffoldConfig(ctx),
+ scaffoldViteConfig(ctx),
  scaffoldRoot(ctx),
  detectLocalePrefix(ctx.cwd),
  scaffoldEnvVars(ctx, SIGN_ROUTE_ENV_VARS.vite),
@@ -404,6 +482,7 @@ export const reactRouter: FrameworkScaffold = {
  const rootAction = rootResult.action;
  const actions = [
  configAction,
+ viteResult.action,
  rootAction,
  ...authActions,
  routesResult.action,
@@ -424,6 +503,12 @@ export const reactRouter: FrameworkScaffold = {
  );
  }
 
+ if (viteResult.needsManualViteWire) {
+ postInstructions.push(
+ "React Router v8 needs `ssr: { noExternal: ['@clerk/react-router'] }` in your vite config — without it, dev SSR fails with \"useNavigate() may be used only in the context of a <Router>\". See: https://github.com/remix-run/react-router/issues/15232",
+ );
+ }
+
  if (rootAction?.type === "modify" && rootResult.needsManualLoaderMerge) {
  postInstructions.push(
  "Update your existing app/root.tsx loader to import and call rootAuthLoader(args), then pass that loaderData to <ClerkProvider>.",

.changeset/react-router-v8-noexternal.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+Fix `clerk init` for React Router v8 projects by adding `@clerk/react-router` to `ssr.noExternal` in the Vite config, preventing dev-mode SSR from failing with "useNavigate() may be used only in the context of a <Router>".

packages/cli-core/src/commands/init/frameworks/react-router.test.ts

@@ -434,3 +434,118 @@ export default [index("routes/home.tsx")] satisfies RouteConfig;
  'route("($locale)/sign-up/*", "routes/($locale).sign-up.tsx")',
  );
 });
+
+test("adds ssr.noExternal to vite.config.ts for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [reactRouter()],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("noExternal");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("appends to an existing ssr.noExternal array for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["some-other-pkg"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("some-other-pkg");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("skips vite config when @clerk/react-router is already in ssr.noExternal", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["@clerk/react-router"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("skip");
+});
+
+test("does not touch vite config for React Router 7", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "7.9.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).not.toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is missing on React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is a function form", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig(({ command }) => ({
+ plugins: [],
+}));
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});

packages/cli-core/src/commands/init/frameworks/react-router.ts

@@ -382,6 +382,83 @@ function scaffoldConfig(ctx: ProjectContext): Promise<FileAction | null> {
  });
 }
 
+type ViteScaffoldResult = {
+ action: FileAction | null;
+ /** True when the noExternal entry is needed but couldn't be applied — user must wire manually. */
+ needsManualViteWire: boolean;
+};
+
+/**
+ * Add `ssr.noExternal: ["@clerk/react-router"]` to the vite config.
+ * React Router v8 ships development/production conditional exports; `react-router dev`
+ * externalizes @clerk/react-router for SSR, so it resolves react-router's production
+ * build while app code gets the development build — two Router contexts, and every
+ * SSR render throws "useNavigate() may be used only in the context of a <Router>".
+ * https://github.com/remix-run/react-router/issues/15232
+ */
+function addClerkNoExternal(content: string): string {
+ try {
+ const mod = parseModule(content);
+ const defaultExport = mod.exports.default;
+ if (!defaultExport || typeof defaultExport !== "object") return content;
+
+ // `export default defineConfig({...})` proxies the call expression; property writes on it
+ // throw, so operate on the call's first argument (the config object) instead.
+ const config = defaultExport.$type === "function-call" ? defaultExport.$args[0] : defaultExport;
+ if (!config || typeof config !== "object") return content;
+
+ if (!config.ssr) config.ssr = {};
+ if (config.ssr.noExternal === undefined) config.ssr.noExternal = [];
+ // boolean/string/regex noExternal: leave it and let the caller emit the manual instruction
+ if (!Array.isArray(config.ssr.noExternal)) return content;
+
+ if (!config.ssr.noExternal.includes("@clerk/react-router")) {
+ config.ssr.noExternal.push("@clerk/react-router");
+ }
+ return mod.generate().code;
+ } catch {
+ return content;
+ }
+}
+
+async function scaffoldViteConfig(ctx: ProjectContext): Promise<ViteScaffoldResult> {
+ // The dual-instance issue only exists in v8's conditional exports; v7 doesn't need this.
+ if (shouldEnableV8MiddlewareFlag(ctx)) return { action: null, needsManualViteWire: false };
+
+ const configPath = await findFirstFile(ctx.cwd, [
+ "vite.config.ts",
+ "vite.config.js",
+ "vite.config.mts",
+ "vite.config.mjs",
+ ]);
+ if (!configPath) return { action: null, needsManualViteWire: true };
+
+ const content = await Bun.file(join(ctx.cwd, configPath)).text();
+ if (content.includes("@clerk/react-router")) {
+ return {
+ action: {
+ type: "skip",
+ path: configPath,
+ skipReason: "Already references @clerk/react-router in vite config",
+ },
+ needsManualViteWire: false,
+ };
+ }
+
+ const updated = addClerkNoExternal(content);
+ if (updated === content) return { action: null, needsManualViteWire: true };
+
+ return {
+ action: {
+ path: configPath,
+ type: "modify",
+ content: updated,
+ description: "Add @clerk/react-router to ssr.noExternal (React Router v8 dev SSR fix)",
+ },
+ needsManualViteWire: false,
+ };
+}
+
 export const reactRouter: FrameworkScaffold = {
  name: "React Router",
  dep: "react-router",
@@ -390,8 +467,9 @@ export const reactRouter: FrameworkScaffold = {
  matches: (ctx) => ctx.framework.dep === "react-router",
 
  async scaffold(ctx: ProjectContext): Promise<ScaffoldPlan> {
- const [configAction, rootResult, localePrefix, envAction] = await Promise.all([
+ const [configAction, viteResult, rootResult, localePrefix, envAction] = await Promise.all([
  scaffoldConfig(ctx),
+ scaffoldViteConfig(ctx),
  scaffoldRoot(ctx),
  detectLocalePrefix(ctx.cwd),
  scaffoldEnvVars(ctx, SIGN_ROUTE_ENV_VARS.vite),
@@ -404,6 +482,7 @@ export const reactRouter: FrameworkScaffold = {
  const rootAction = rootResult.action;
  const actions = [
  configAction,
+ viteResult.action,
  rootAction,
  ...authActions,
  routesResult.action,
@@ -424,6 +503,12 @@ export const reactRouter: FrameworkScaffold = {
  );
  }
 
+ if (viteResult.needsManualViteWire) {
+ postInstructions.push(
+ "React Router v8 needs `ssr: { noExternal: ['@clerk/react-router'] }` in your vite config — without it, dev SSR fails with \"useNavigate() may be used only in the context of a <Router>\". See: https://github.com/remix-run/react-router/issues/15232",
+ );
+ }
+
  if (rootAction?.type === "modify" && rootResult.needsManualLoaderMerge) {
  postInstructions.push(
  "Update your existing app/root.tsx loader to import and call rootAuthLoader(args), then pass that loaderData to <ClerkProvider>.",

.changeset/react-router-v8-noexternal.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+Fix `clerk init` for React Router v8 projects by adding `@clerk/react-router` to `ssr.noExternal` in the Vite config, preventing dev-mode SSR from failing with "useNavigate() may be used only in the context of a <Router>".

packages/cli-core/src/commands/init/frameworks/react-router.test.ts

@@ -434,3 +434,118 @@ export default [index("routes/home.tsx")] satisfies RouteConfig;
  'route("($locale)/sign-up/*", "routes/($locale).sign-up.tsx")',
  );
 });
+
+test("adds ssr.noExternal to vite.config.ts for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [reactRouter()],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("noExternal");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("appends to an existing ssr.noExternal array for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["some-other-pkg"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("some-other-pkg");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("skips vite config when @clerk/react-router is already in ssr.noExternal", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["@clerk/react-router"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("skip");
+});
+
+test("does not touch vite config for React Router 7", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "7.9.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).not.toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is missing on React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is a function form", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig(({ command }) => ({
+ plugins: [],
+}));
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});

packages/cli-core/src/commands/init/frameworks/react-router.ts

@@ -382,6 +382,83 @@ function scaffoldConfig(ctx: ProjectContext): Promise<FileAction | null> {
  });
 }
 
+type ViteScaffoldResult = {
+ action: FileAction | null;
+ /** True when the noExternal entry is needed but couldn't be applied — user must wire manually. */
+ needsManualViteWire: boolean;
+};
+
+/**
+ * Add `ssr.noExternal: ["@clerk/react-router"]` to the vite config.
+ * React Router v8 ships development/production conditional exports; `react-router dev`
+ * externalizes @clerk/react-router for SSR, so it resolves react-router's production
+ * build while app code gets the development build — two Router contexts, and every
+ * SSR render throws "useNavigate() may be used only in the context of a <Router>".
+ * https://github.com/remix-run/react-router/issues/15232
+ */
+function addClerkNoExternal(content: string): string {
+ try {
+ const mod = parseModule(content);
+ const defaultExport = mod.exports.default;
+ if (!defaultExport || typeof defaultExport !== "object") return content;
+
+ // `export default defineConfig({...})` proxies the call expression; property writes on it
+ // throw, so operate on the call's first argument (the config object) instead.
+ const config = defaultExport.$type === "function-call" ? defaultExport.$args[0] : defaultExport;
+ if (!config || typeof config !== "object") return content;
+
+ if (!config.ssr) config.ssr = {};
+ if (config.ssr.noExternal === undefined) config.ssr.noExternal = [];
+ // boolean/string/regex noExternal: leave it and let the caller emit the manual instruction
+ if (!Array.isArray(config.ssr.noExternal)) return content;
+
+ if (!config.ssr.noExternal.includes("@clerk/react-router")) {
+ config.ssr.noExternal.push("@clerk/react-router");
+ }
+ return mod.generate().code;
+ } catch {
+ return content;
+ }
+}
+
+async function scaffoldViteConfig(ctx: ProjectContext): Promise<ViteScaffoldResult> {
+ // The dual-instance issue only exists in v8's conditional exports; v7 doesn't need this.
+ if (shouldEnableV8MiddlewareFlag(ctx)) return { action: null, needsManualViteWire: false };
+
+ const configPath = await findFirstFile(ctx.cwd, [
+ "vite.config.ts",
+ "vite.config.js",
+ "vite.config.mts",
+ "vite.config.mjs",
+ ]);
+ if (!configPath) return { action: null, needsManualViteWire: true };
+
+ const content = await Bun.file(join(ctx.cwd, configPath)).text();
+ if (content.includes("@clerk/react-router")) {
+ return {
+ action: {
+ type: "skip",
+ path: configPath,
+ skipReason: "Already references @clerk/react-router in vite config",
+ },
+ needsManualViteWire: false,
+ };
+ }
+
+ const updated = addClerkNoExternal(content);
+ if (updated === content) return { action: null, needsManualViteWire: true };
+
+ return {
+ action: {
+ path: configPath,
+ type: "modify",
+ content: updated,
+ description: "Add @clerk/react-router to ssr.noExternal (React Router v8 dev SSR fix)",
+ },
+ needsManualViteWire: false,
+ };
+}
+
 export const reactRouter: FrameworkScaffold = {
  name: "React Router",
  dep: "react-router",
@@ -390,8 +467,9 @@ export const reactRouter: FrameworkScaffold = {
  matches: (ctx) => ctx.framework.dep === "react-router",
 
  async scaffold(ctx: ProjectContext): Promise<ScaffoldPlan> {
- const [configAction, rootResult, localePrefix, envAction] = await Promise.all([
+ const [configAction, viteResult, rootResult, localePrefix, envAction] = await Promise.all([
  scaffoldConfig(ctx),
+ scaffoldViteConfig(ctx),
  scaffoldRoot(ctx),
  detectLocalePrefix(ctx.cwd),
  scaffoldEnvVars(ctx, SIGN_ROUTE_ENV_VARS.vite),
@@ -404,6 +482,7 @@ export const reactRouter: FrameworkScaffold = {
  const rootAction = rootResult.action;
  const actions = [
  configAction,
+ viteResult.action,
  rootAction,
  ...authActions,
  routesResult.action,
@@ -424,6 +503,12 @@ export const reactRouter: FrameworkScaffold = {
  );
  }
 
+ if (viteResult.needsManualViteWire) {
+ postInstructions.push(
+ "React Router v8 needs `ssr: { noExternal: ['@clerk/react-router'] }` in your vite config — without it, dev SSR fails with \"useNavigate() may be used only in the context of a <Router>\". See: https://github.com/remix-run/react-router/issues/15232",
+ );
+ }
+
  if (rootAction?.type === "modify" && rootResult.needsManualLoaderMerge) {
  postInstructions.push(
  "Update your existing app/root.tsx loader to import and call rootAuthLoader(args), then pass that loaderData to <ClerkProvider>.",

.changeset/react-router-v8-noexternal.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+Fix `clerk init` for React Router v8 projects by adding `@clerk/react-router` to `ssr.noExternal` in the Vite config, preventing dev-mode SSR from failing with "useNavigate() may be used only in the context of a <Router>".

packages/cli-core/src/commands/init/frameworks/react-router.test.ts

@@ -434,3 +434,118 @@ export default [index("routes/home.tsx")] satisfies RouteConfig;
  'route("($locale)/sign-up/*", "routes/($locale).sign-up.tsx")',
  );
 });
+
+test("adds ssr.noExternal to vite.config.ts for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [reactRouter()],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("noExternal");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("appends to an existing ssr.noExternal array for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["some-other-pkg"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("some-other-pkg");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("skips vite config when @clerk/react-router is already in ssr.noExternal", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["@clerk/react-router"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("skip");
+});
+
+test("does not touch vite config for React Router 7", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "7.9.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).not.toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is missing on React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is a function form", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig(({ command }) => ({
+ plugins: [],
+}));
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});

packages/cli-core/src/commands/init/frameworks/react-router.ts

@@ -382,6 +382,83 @@ function scaffoldConfig(ctx: ProjectContext): Promise<FileAction | null> {
  });
 }
 
+type ViteScaffoldResult = {
+ action: FileAction | null;
+ /** True when the noExternal entry is needed but couldn't be applied — user must wire manually. */
+ needsManualViteWire: boolean;
+};
+
+/**
+ * Add `ssr.noExternal: ["@clerk/react-router"]` to the vite config.
+ * React Router v8 ships development/production conditional exports; `react-router dev`
+ * externalizes @clerk/react-router for SSR, so it resolves react-router's production
+ * build while app code gets the development build — two Router contexts, and every
+ * SSR render throws "useNavigate() may be used only in the context of a <Router>".
+ * https://github.com/remix-run/react-router/issues/15232
+ */
+function addClerkNoExternal(content: string): string {
+ try {
+ const mod = parseModule(content);
+ const defaultExport = mod.exports.default;
+ if (!defaultExport || typeof defaultExport !== "object") return content;
+
+ // `export default defineConfig({...})` proxies the call expression; property writes on it
+ // throw, so operate on the call's first argument (the config object) instead.
+ const config = defaultExport.$type === "function-call" ? defaultExport.$args[0] : defaultExport;
+ if (!config || typeof config !== "object") return content;
+
+ if (!config.ssr) config.ssr = {};
+ if (config.ssr.noExternal === undefined) config.ssr.noExternal = [];
+ // boolean/string/regex noExternal: leave it and let the caller emit the manual instruction
+ if (!Array.isArray(config.ssr.noExternal)) return content;
+
+ if (!config.ssr.noExternal.includes("@clerk/react-router")) {
+ config.ssr.noExternal.push("@clerk/react-router");
+ }
+ return mod.generate().code;
+ } catch {
+ return content;
+ }
+}
+
+async function scaffoldViteConfig(ctx: ProjectContext): Promise<ViteScaffoldResult> {
+ // The dual-instance issue only exists in v8's conditional exports; v7 doesn't need this.
+ if (shouldEnableV8MiddlewareFlag(ctx)) return { action: null, needsManualViteWire: false };
+
+ const configPath = await findFirstFile(ctx.cwd, [
+ "vite.config.ts",
+ "vite.config.js",
+ "vite.config.mts",
+ "vite.config.mjs",
+ ]);
+ if (!configPath) return { action: null, needsManualViteWire: true };
+
+ const content = await Bun.file(join(ctx.cwd, configPath)).text();
+ if (content.includes("@clerk/react-router")) {
+ return {
+ action: {
+ type: "skip",
+ path: configPath,
+ skipReason: "Already references @clerk/react-router in vite config",
+ },
+ needsManualViteWire: false,
+ };
+ }
+
+ const updated = addClerkNoExternal(content);
+ if (updated === content) return { action: null, needsManualViteWire: true };
+
+ return {
+ action: {
+ path: configPath,
+ type: "modify",
+ content: updated,
+ description: "Add @clerk/react-router to ssr.noExternal (React Router v8 dev SSR fix)",
+ },
+ needsManualViteWire: false,
+ };
+}
+
 export const reactRouter: FrameworkScaffold = {
  name: "React Router",
  dep: "react-router",
@@ -390,8 +467,9 @@ export const reactRouter: FrameworkScaffold = {
  matches: (ctx) => ctx.framework.dep === "react-router",
 
  async scaffold(ctx: ProjectContext): Promise<ScaffoldPlan> {
- const [configAction, rootResult, localePrefix, envAction] = await Promise.all([
+ const [configAction, viteResult, rootResult, localePrefix, envAction] = await Promise.all([
  scaffoldConfig(ctx),
+ scaffoldViteConfig(ctx),
  scaffoldRoot(ctx),
  detectLocalePrefix(ctx.cwd),
  scaffoldEnvVars(ctx, SIGN_ROUTE_ENV_VARS.vite),
@@ -404,6 +482,7 @@ export const reactRouter: FrameworkScaffold = {
  const rootAction = rootResult.action;
  const actions = [
  configAction,
+ viteResult.action,
  rootAction,
  ...authActions,
  routesResult.action,
@@ -424,6 +503,12 @@ export const reactRouter: FrameworkScaffold = {
  );
  }
 
+ if (viteResult.needsManualViteWire) {
+ postInstructions.push(
+ "React Router v8 needs `ssr: { noExternal: ['@clerk/react-router'] }` in your vite config — without it, dev SSR fails with \"useNavigate() may be used only in the context of a <Router>\". See: https://github.com/remix-run/react-router/issues/15232",
+ );
+ }
+
  if (rootAction?.type === "modify" && rootResult.needsManualLoaderMerge) {
  postInstructions.push(
  "Update your existing app/root.tsx loader to import and call rootAuthLoader(args), then pass that loaderData to <ClerkProvider>.",

.changeset/react-router-v8-noexternal.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+Fix `clerk init` for React Router v8 projects by adding `@clerk/react-router` to `ssr.noExternal` in the Vite config, preventing dev-mode SSR from failing with "useNavigate() may be used only in the context of a <Router>".

packages/cli-core/src/commands/init/frameworks/react-router.test.ts

@@ -434,3 +434,118 @@ export default [index("routes/home.tsx")] satisfies RouteConfig;
  'route("($locale)/sign-up/*", "routes/($locale).sign-up.tsx")',
  );
 });
+
+test("adds ssr.noExternal to vite.config.ts for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [reactRouter()],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("noExternal");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("appends to an existing ssr.noExternal array for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["some-other-pkg"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("some-other-pkg");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("skips vite config when @clerk/react-router is already in ssr.noExternal", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["@clerk/react-router"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("skip");
+});
+
+test("does not touch vite config for React Router 7", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "7.9.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).not.toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is missing on React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is a function form", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig(({ command }) => ({
+ plugins: [],
+}));
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});

packages/cli-core/src/commands/init/frameworks/react-router.ts

@@ -382,6 +382,83 @@ function scaffoldConfig(ctx: ProjectContext): Promise<FileAction | null> {
  });
 }
 
+type ViteScaffoldResult = {
+ action: FileAction | null;
+ /** True when the noExternal entry is needed but couldn't be applied — user must wire manually. */
+ needsManualViteWire: boolean;
+};
+
+/**
+ * Add `ssr.noExternal: ["@clerk/react-router"]` to the vite config.
+ * React Router v8 ships development/production conditional exports; `react-router dev`
+ * externalizes @clerk/react-router for SSR, so it resolves react-router's production
+ * build while app code gets the development build — two Router contexts, and every
+ * SSR render throws "useNavigate() may be used only in the context of a <Router>".
+ * https://github.com/remix-run/react-router/issues/15232
+ */
+function addClerkNoExternal(content: string): string {
+ try {
+ const mod = parseModule(content);
+ const defaultExport = mod.exports.default;
+ if (!defaultExport || typeof defaultExport !== "object") return content;
+
+ // `export default defineConfig({...})` proxies the call expression; property writes on it
+ // throw, so operate on the call's first argument (the config object) instead.
+ const config = defaultExport.$type === "function-call" ? defaultExport.$args[0] : defaultExport;
+ if (!config || typeof config !== "object") return content;
+
+ if (!config.ssr) config.ssr = {};
+ if (config.ssr.noExternal === undefined) config.ssr.noExternal = [];
+ // boolean/string/regex noExternal: leave it and let the caller emit the manual instruction
+ if (!Array.isArray(config.ssr.noExternal)) return content;
+
+ if (!config.ssr.noExternal.includes("@clerk/react-router")) {
+ config.ssr.noExternal.push("@clerk/react-router");
+ }
+ return mod.generate().code;
+ } catch {
+ return content;
+ }
+}
+
+async function scaffoldViteConfig(ctx: ProjectContext): Promise<ViteScaffoldResult> {
+ // The dual-instance issue only exists in v8's conditional exports; v7 doesn't need this.
+ if (shouldEnableV8MiddlewareFlag(ctx)) return { action: null, needsManualViteWire: false };
+
+ const configPath = await findFirstFile(ctx.cwd, [
+ "vite.config.ts",
+ "vite.config.js",
+ "vite.config.mts",
+ "vite.config.mjs",
+ ]);
+ if (!configPath) return { action: null, needsManualViteWire: true };
+
+ const content = await Bun.file(join(ctx.cwd, configPath)).text();
+ if (content.includes("@clerk/react-router")) {
+ return {
+ action: {
+ type: "skip",
+ path: configPath,
+ skipReason: "Already references @clerk/react-router in vite config",
+ },
+ needsManualViteWire: false,
+ };
+ }
+
+ const updated = addClerkNoExternal(content);
+ if (updated === content) return { action: null, needsManualViteWire: true };
+
+ return {
+ action: {
+ path: configPath,
+ type: "modify",
+ content: updated,
+ description: "Add @clerk/react-router to ssr.noExternal (React Router v8 dev SSR fix)",
+ },
+ needsManualViteWire: false,
+ };
+}
+
 export const reactRouter: FrameworkScaffold = {
  name: "React Router",
  dep: "react-router",
@@ -390,8 +467,9 @@ export const reactRouter: FrameworkScaffold = {
  matches: (ctx) => ctx.framework.dep === "react-router",
 
  async scaffold(ctx: ProjectContext): Promise<ScaffoldPlan> {
- const [configAction, rootResult, localePrefix, envAction] = await Promise.all([
+ const [configAction, viteResult, rootResult, localePrefix, envAction] = await Promise.all([
  scaffoldConfig(ctx),
+ scaffoldViteConfig(ctx),
  scaffoldRoot(ctx),
  detectLocalePrefix(ctx.cwd),
  scaffoldEnvVars(ctx, SIGN_ROUTE_ENV_VARS.vite),
@@ -404,6 +482,7 @@ export const reactRouter: FrameworkScaffold = {
  const rootAction = rootResult.action;
  const actions = [
  configAction,
+ viteResult.action,
  rootAction,
  ...authActions,
  routesResult.action,
@@ -424,6 +503,12 @@ export const reactRouter: FrameworkScaffold = {
  );
  }
 
+ if (viteResult.needsManualViteWire) {
+ postInstructions.push(
+ "React Router v8 needs `ssr: { noExternal: ['@clerk/react-router'] }` in your vite config — without it, dev SSR fails with \"useNavigate() may be used only in the context of a <Router>\". See: https://github.com/remix-run/react-router/issues/15232",
+ );
+ }
+
  if (rootAction?.type === "modify" && rootResult.needsManualLoaderMerge) {
  postInstructions.push(
  "Update your existing app/root.tsx loader to import and call rootAuthLoader(args), then pass that loaderData to <ClerkProvider>.",

.changeset/react-router-v8-noexternal.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+Fix `clerk init` for React Router v8 projects by adding `@clerk/react-router` to `ssr.noExternal` in the Vite config, preventing dev-mode SSR from failing with "useNavigate() may be used only in the context of a <Router>".

packages/cli-core/src/commands/init/frameworks/react-router.test.ts

@@ -434,3 +434,118 @@ export default [index("routes/home.tsx")] satisfies RouteConfig;
  'route("($locale)/sign-up/*", "routes/($locale).sign-up.tsx")',
  );
 });
+
+test("adds ssr.noExternal to vite.config.ts for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [reactRouter()],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("noExternal");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("appends to an existing ssr.noExternal array for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["some-other-pkg"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("some-other-pkg");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("skips vite config when @clerk/react-router is already in ssr.noExternal", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["@clerk/react-router"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("skip");
+});
+
+test("does not touch vite config for React Router 7", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "7.9.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).not.toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is missing on React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is a function form", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig(({ command }) => ({
+ plugins: [],
+}));
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});

packages/cli-core/src/commands/init/frameworks/react-router.ts

@@ -382,6 +382,83 @@ function scaffoldConfig(ctx: ProjectContext): Promise<FileAction | null> {
  });
 }
 
+type ViteScaffoldResult = {
+ action: FileAction | null;
+ /** True when the noExternal entry is needed but couldn't be applied — user must wire manually. */
+ needsManualViteWire: boolean;
+};
+
+/**
+ * Add `ssr.noExternal: ["@clerk/react-router"]` to the vite config.
+ * React Router v8 ships development/production conditional exports; `react-router dev`
+ * externalizes @clerk/react-router for SSR, so it resolves react-router's production
+ * build while app code gets the development build — two Router contexts, and every
+ * SSR render throws "useNavigate() may be used only in the context of a <Router>".
+ * https://github.com/remix-run/react-router/issues/15232
+ */
+function addClerkNoExternal(content: string): string {
+ try {
+ const mod = parseModule(content);
+ const defaultExport = mod.exports.default;
+ if (!defaultExport || typeof defaultExport !== "object") return content;
+
+ // `export default defineConfig({...})` proxies the call expression; property writes on it
+ // throw, so operate on the call's first argument (the config object) instead.
+ const config = defaultExport.$type === "function-call" ? defaultExport.$args[0] : defaultExport;
+ if (!config || typeof config !== "object") return content;
+
+ if (!config.ssr) config.ssr = {};
+ if (config.ssr.noExternal === undefined) config.ssr.noExternal = [];
+ // boolean/string/regex noExternal: leave it and let the caller emit the manual instruction
+ if (!Array.isArray(config.ssr.noExternal)) return content;
+
+ if (!config.ssr.noExternal.includes("@clerk/react-router")) {
+ config.ssr.noExternal.push("@clerk/react-router");
+ }
+ return mod.generate().code;
+ } catch {
+ return content;
+ }
+}
+
+async function scaffoldViteConfig(ctx: ProjectContext): Promise<ViteScaffoldResult> {
+ // The dual-instance issue only exists in v8's conditional exports; v7 doesn't need this.
+ if (shouldEnableV8MiddlewareFlag(ctx)) return { action: null, needsManualViteWire: false };
+
+ const configPath = await findFirstFile(ctx.cwd, [
+ "vite.config.ts",
+ "vite.config.js",
+ "vite.config.mts",
+ "vite.config.mjs",
+ ]);
+ if (!configPath) return { action: null, needsManualViteWire: true };
+
+ const content = await Bun.file(join(ctx.cwd, configPath)).text();
+ if (content.includes("@clerk/react-router")) {
+ return {
+ action: {
+ type: "skip",
+ path: configPath,
+ skipReason: "Already references @clerk/react-router in vite config",
+ },
+ needsManualViteWire: false,
+ };
+ }
+
+ const updated = addClerkNoExternal(content);
+ if (updated === content) return { action: null, needsManualViteWire: true };
+
+ return {
+ action: {
+ path: configPath,
+ type: "modify",
+ content: updated,
+ description: "Add @clerk/react-router to ssr.noExternal (React Router v8 dev SSR fix)",
+ },
+ needsManualViteWire: false,
+ };
+}
+
 export const reactRouter: FrameworkScaffold = {
  name: "React Router",
  dep: "react-router",
@@ -390,8 +467,9 @@ export const reactRouter: FrameworkScaffold = {
  matches: (ctx) => ctx.framework.dep === "react-router",
 
  async scaffold(ctx: ProjectContext): Promise<ScaffoldPlan> {
- const [configAction, rootResult, localePrefix, envAction] = await Promise.all([
+ const [configAction, viteResult, rootResult, localePrefix, envAction] = await Promise.all([
  scaffoldConfig(ctx),
+ scaffoldViteConfig(ctx),
  scaffoldRoot(ctx),
  detectLocalePrefix(ctx.cwd),
  scaffoldEnvVars(ctx, SIGN_ROUTE_ENV_VARS.vite),
@@ -404,6 +482,7 @@ export const reactRouter: FrameworkScaffold = {
  const rootAction = rootResult.action;
  const actions = [
  configAction,
+ viteResult.action,
  rootAction,
  ...authActions,
  routesResult.action,
@@ -424,6 +503,12 @@ export const reactRouter: FrameworkScaffold = {
  );
  }
 
+ if (viteResult.needsManualViteWire) {
+ postInstructions.push(
+ "React Router v8 needs `ssr: { noExternal: ['@clerk/react-router'] }` in your vite config — without it, dev SSR fails with \"useNavigate() may be used only in the context of a <Router>\". See: https://github.com/remix-run/react-router/issues/15232",
+ );
+ }
+
  if (rootAction?.type === "modify" && rootResult.needsManualLoaderMerge) {
  postInstructions.push(
  "Update your existing app/root.tsx loader to import and call rootAuthLoader(args), then pass that loaderData to <ClerkProvider>.",

.changeset/react-router-v8-noexternal.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+Fix `clerk init` for React Router v8 projects by adding `@clerk/react-router` to `ssr.noExternal` in the Vite config, preventing dev-mode SSR from failing with "useNavigate() may be used only in the context of a <Router>".

packages/cli-core/src/commands/init/frameworks/react-router.test.ts

@@ -434,3 +434,118 @@ export default [index("routes/home.tsx")] satisfies RouteConfig;
  'route("($locale)/sign-up/*", "routes/($locale).sign-up.tsx")',
  );
 });
+
+test("adds ssr.noExternal to vite.config.ts for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [reactRouter()],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("noExternal");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("appends to an existing ssr.noExternal array for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["some-other-pkg"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("some-other-pkg");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("skips vite config when @clerk/react-router is already in ssr.noExternal", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["@clerk/react-router"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("skip");
+});
+
+test("does not touch vite config for React Router 7", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "7.9.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).not.toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is missing on React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is a function form", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig(({ command }) => ({
+ plugins: [],
+}));
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});

packages/cli-core/src/commands/init/frameworks/react-router.ts

@@ -382,6 +382,83 @@ function scaffoldConfig(ctx: ProjectContext): Promise<FileAction | null> {
  });
 }
 
+type ViteScaffoldResult = {
+ action: FileAction | null;
+ /** True when the noExternal entry is needed but couldn't be applied — user must wire manually. */
+ needsManualViteWire: boolean;
+};
+
+/**
+ * Add `ssr.noExternal: ["@clerk/react-router"]` to the vite config.
+ * React Router v8 ships development/production conditional exports; `react-router dev`
+ * externalizes @clerk/react-router for SSR, so it resolves react-router's production
+ * build while app code gets the development build — two Router contexts, and every
+ * SSR render throws "useNavigate() may be used only in the context of a <Router>".
+ * https://github.com/remix-run/react-router/issues/15232
+ */
+function addClerkNoExternal(content: string): string {
+ try {
+ const mod = parseModule(content);
+ const defaultExport = mod.exports.default;
+ if (!defaultExport || typeof defaultExport !== "object") return content;
+
+ // `export default defineConfig({...})` proxies the call expression; property writes on it
+ // throw, so operate on the call's first argument (the config object) instead.
+ const config = defaultExport.$type === "function-call" ? defaultExport.$args[0] : defaultExport;
+ if (!config || typeof config !== "object") return content;
+
+ if (!config.ssr) config.ssr = {};
+ if (config.ssr.noExternal === undefined) config.ssr.noExternal = [];
+ // boolean/string/regex noExternal: leave it and let the caller emit the manual instruction
+ if (!Array.isArray(config.ssr.noExternal)) return content;
+
+ if (!config.ssr.noExternal.includes("@clerk/react-router")) {
+ config.ssr.noExternal.push("@clerk/react-router");
+ }
+ return mod.generate().code;
+ } catch {
+ return content;
+ }
+}
+
+async function scaffoldViteConfig(ctx: ProjectContext): Promise<ViteScaffoldResult> {
+ // The dual-instance issue only exists in v8's conditional exports; v7 doesn't need this.
+ if (shouldEnableV8MiddlewareFlag(ctx)) return { action: null, needsManualViteWire: false };
+
+ const configPath = await findFirstFile(ctx.cwd, [
+ "vite.config.ts",
+ "vite.config.js",
+ "vite.config.mts",
+ "vite.config.mjs",
+ ]);
+ if (!configPath) return { action: null, needsManualViteWire: true };
+
+ const content = await Bun.file(join(ctx.cwd, configPath)).text();
+ if (content.includes("@clerk/react-router")) {
+ return {
+ action: {
+ type: "skip",
+ path: configPath,
+ skipReason: "Already references @clerk/react-router in vite config",
+ },
+ needsManualViteWire: false,
+ };
+ }
+
+ const updated = addClerkNoExternal(content);
+ if (updated === content) return { action: null, needsManualViteWire: true };
+
+ return {
+ action: {
+ path: configPath,
+ type: "modify",
+ content: updated,
+ description: "Add @clerk/react-router to ssr.noExternal (React Router v8 dev SSR fix)",
+ },
+ needsManualViteWire: false,
+ };
+}
+
 export const reactRouter: FrameworkScaffold = {
  name: "React Router",
  dep: "react-router",
@@ -390,8 +467,9 @@ export const reactRouter: FrameworkScaffold = {
  matches: (ctx) => ctx.framework.dep === "react-router",
 
  async scaffold(ctx: ProjectContext): Promise<ScaffoldPlan> {
- const [configAction, rootResult, localePrefix, envAction] = await Promise.all([
+ const [configAction, viteResult, rootResult, localePrefix, envAction] = await Promise.all([
  scaffoldConfig(ctx),
+ scaffoldViteConfig(ctx),
  scaffoldRoot(ctx),
  detectLocalePrefix(ctx.cwd),
  scaffoldEnvVars(ctx, SIGN_ROUTE_ENV_VARS.vite),
@@ -404,6 +482,7 @@ export const reactRouter: FrameworkScaffold = {
  const rootAction = rootResult.action;
  const actions = [
  configAction,
+ viteResult.action,
  rootAction,
  ...authActions,
  routesResult.action,
@@ -424,6 +503,12 @@ export const reactRouter: FrameworkScaffold = {
  );
  }
 
+ if (viteResult.needsManualViteWire) {
+ postInstructions.push(
+ "React Router v8 needs `ssr: { noExternal: ['@clerk/react-router'] }` in your vite config — without it, dev SSR fails with \"useNavigate() may be used only in the context of a <Router>\". See: https://github.com/remix-run/react-router/issues/15232",
+ );
+ }
+
  if (rootAction?.type === "modify" && rootResult.needsManualLoaderMerge) {
  postInstructions.push(
  "Update your existing app/root.tsx loader to import and call rootAuthLoader(args), then pass that loaderData to <ClerkProvider>.",

.changeset/react-router-v8-noexternal.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+Fix `clerk init` for React Router v8 projects by adding `@clerk/react-router` to `ssr.noExternal` in the Vite config, preventing dev-mode SSR from failing with "useNavigate() may be used only in the context of a <Router>".

packages/cli-core/src/commands/init/frameworks/react-router.test.ts

@@ -434,3 +434,118 @@ export default [index("routes/home.tsx")] satisfies RouteConfig;
  'route("($locale)/sign-up/*", "routes/($locale).sign-up.tsx")',
  );
 });
+
+test("adds ssr.noExternal to vite.config.ts for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [reactRouter()],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("noExternal");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("appends to an existing ssr.noExternal array for React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["some-other-pkg"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("modify");
+ if (viteAction?.type !== "modify") throw new Error("Expected vite config modify action");
+
+ expect(viteAction.content).toContain("some-other-pkg");
+ expect(viteAction.content).toContain("@clerk/react-router");
+ expect(viteAction.content.match(/ssr\s*:/g)?.length).toBe(1);
+});
+
+test("skips vite config when @clerk/react-router is already in ssr.noExternal", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ ssr: {
+ noExternal: ["@clerk/react-router"],
+ },
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction?.type).toBe("skip");
+});
+
+test("does not touch vite config for React Router 7", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [],
+});
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "7.9.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).not.toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is missing on React Router 8", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});
+
+test("emits manual noExternal instruction when vite config is a function form", async () => {
+ await mkdir(join(tempDir, "app"), { recursive: true });
+ await Bun.write(
+ join(tempDir, "vite.config.ts"),
+ `import { defineConfig } from "vite";
+
+export default defineConfig(({ command }) => ({
+ plugins: [],
+}));
+`,
+ );
+
+ const plan = await reactRouter.scaffold(makeCtx({ deps: { "react-router": "8.0.0" } }));
+ const viteAction = plan.actions.find((action) => action.path === "vite.config.ts");
+
+ expect(viteAction).toBeUndefined();
+ expect(plan.postInstructions.join(" ")).toContain("noExternal");
+});

packages/cli-core/src/commands/init/frameworks/react-router.ts

@@ -382,6 +382,83 @@ function scaffoldConfig(ctx: ProjectContext): Promise<FileAction | null> {
  });
 }
 
+type ViteScaffoldResult = {
+ action: FileAction | null;
+ /** True when the noExternal entry is needed but couldn't be applied — user must wire manually. */
+ needsManualViteWire: boolean;
+};
+
+/**
+ * Add `ssr.noExternal: ["@clerk/react-router"]` to the vite config.
+ * React Router v8 ships development/production conditional exports; `react-router dev`
+ * externalizes @clerk/react-router for SSR, so it resolves react-router's production
+ * build while app code gets the development build — two Router contexts, and every
+ * SSR render throws "useNavigate() may be used only in the context of a <Router>".
+ * https://github.com/remix-run/react-router/issues/15232
+ */
+function addClerkNoExternal(content: string): string {
+ try {
+ const mod = parseModule(content);
+ const defaultExport = mod.exports.default;
+ if (!defaultExport || typeof defaultExport !== "object") return content;
+
+ // `export default defineConfig({...})` proxies the call expression; property writes on it
+ // throw, so operate on the call's first argument (the config object) instead.
+ const config = defaultExport.$type === "function-call" ? defaultExport.$args[0] : defaultExport;
+ if (!config || typeof config !== "object") return content;
+
+ if (!config.ssr) config.ssr = {};
+ if (config.ssr.noExternal === undefined) config.ssr.noExternal = [];
+ // boolean/string/regex noExternal: leave it and let the caller emit the manual instruction
+ if (!Array.isArray(config.ssr.noExternal)) return content;
+
+ if (!config.ssr.noExternal.includes("@clerk/react-router")) {
+ config.ssr.noExternal.push("@clerk/react-router");
+ }
+ return mod.generate().code;
+ } catch {
+ return content;
+ }
+}
+
+async function scaffoldViteConfig(ctx: ProjectContext): Promise<ViteScaffoldResult> {
+ // The dual-instance issue only exists in v8's conditional exports; v7 doesn't need this.
+ if (shouldEnableV8MiddlewareFlag(ctx)) return { action: null, needsManualViteWire: false };
+
+ const configPath = await findFirstFile(ctx.cwd, [
+ "vite.config.ts",
+ "vite.config.js",
+ "vite.config.mts",
+ "vite.config.mjs",
+ ]);
+ if (!configPath) return { action: null, needsManualViteWire: true };
+
+ const content = await Bun.file(join(ctx.cwd, configPath)).text();
+ if (content.includes("@clerk/react-router")) {
+ return {
+ action: {
+ type: "skip",
+ path: configPath,
+ skipReason: "Already references @clerk/react-router in vite config",
+ },
+ needsManualViteWire: false,
+ };
+ }
+
+ const updated = addClerkNoExternal(content);
+ if (updated === content) return { action: null, needsManualViteWire: true };
+
+ return {
+ action: {
+ path: configPath,
+ type: "modify",
+ content: updated,
+ description: "Add @clerk/react-router to ssr.noExternal (React Router v8 dev SSR fix)",
+ },
+ needsManualViteWire: false,
+ };
+}
+
 export const reactRouter: FrameworkScaffold = {
  name: "React Router",
  dep: "react-router",
@@ -390,8 +467,9 @@ export const reactRouter: FrameworkScaffold = {
  matches: (ctx) => ctx.framework.dep === "react-router",
 
  async scaffold(ctx: ProjectContext): Promise<ScaffoldPlan> {
- const [configAction, rootResult, localePrefix, envAction] = await Promise.all([
+ const [configAction, viteResult, rootResult, localePrefix, envAction] = await Promise.all([
  scaffoldConfig(ctx),
+ scaffoldViteConfig(ctx),
  scaffoldRoot(ctx),
  detectLocalePrefix(ctx.cwd),
  scaffoldEnvVars(ctx, SIGN_ROUTE_ENV_VARS.vite),
@@ -404,6 +482,7 @@ export const reactRouter: FrameworkScaffold = {
  const rootAction = rootResult.action;
  const actions = [
  configAction,
+ viteResult.action,
  rootAction,
  ...authActions,
  routesResult.action,
@@ -424,6 +503,12 @@ export const reactRouter: FrameworkScaffold = {
  );
  }
 
+ if (viteResult.needsManualViteWire) {
+ postInstructions.push(
+ "React Router v8 needs `ssr: { noExternal: ['@clerk/react-router'] }` in your vite config — without it, dev SSR fails with \"useNavigate() may be used only in the context of a <Router>\". See: https://github.com/remix-run/react-router/issues/15232",
+ );
+ }
+
  if (rootAction?.type === "modify" && rootResult.needsManualLoaderMerge) {
  postInstructions.push(
  "Update your existing app/root.tsx loader to import and call rootAuthLoader(args), then pass that loaderData to <ClerkProvider>.",