{"record":{"id":"3d817ae223c9d980","repo":"remix-run/react-router","slug":"when-using-the-react-router-basename-and-the-vit","errorCode":null,"errorMessage":"When using the React Router `basename` and the Vite `base` config, the `basename` config must begin with `base` for the default Vite dev server.","messagePattern":"When using the React Router `basename` and the Vite `base` config, the `basename` config must begin with `base` for the default Vite dev server\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/react-router-dev/vite/rsc/plugin.ts","lineNumber":194,"sourceCode":"            if (errors.length) {\n              return `RSC Framework Mode does not currently support the following React Router config:\\n${errors.map((x) => ` - ${x}`).join(\"\\n\")}\\n`;\n            }\n          },\n        });\n        configLoader = await configLoaderPromise;\n\n        const configResult = await configLoader.getConfig();\n        if (!configResult.ok) throw new Error(configResult.error);\n        updateConfig(configResult.value);\n\n        if (\n          viteUserConfig.base &&\n          config.basename !== \"/\" &&\n          viteCommand === \"serve\" &&\n          !viteUserConfig.server?.middlewareMode &&\n          !config.basename.startsWith(viteUserConfig.base)\n        ) {\n          throw new Error(\n            \"When using the React Router `basename` and the Vite `base` config, \" +\n              \"the `basename` config must begin with `base` for the default \" +\n              \"Vite dev server.\",\n          );\n        }\n\n        const vite = await import(\"vite\");\n        logger = vite.createLogger(viteUserConfig.logLevel, {\n          prefix: \"[react-router]\",\n        });\n\n        entries = await resolveRSCEntryFiles({\n          reactRouterConfig: config,\n        });\n\n        // Async import here to avoid CJS warnings on the console\n        let viteNormalizePath = (await import(\"vite\")).normalizePath;\n        let optimizeDepsEntries = getOptimizeDepsEntries({","sourceCodeStart":176,"sourceCodeEnd":212,"githubUrl":"https://github.com/remix-run/react-router/blob/6beaca39526d5716c3c112ebb0782765baa5a9ce/packages/react-router-dev/vite/rsc/plugin.ts#L176-L212","documentation":"In the RSC Framework-mode Vite plugin, when running the default dev server (viteCommand 'serve' and server.middlewareMode falsy), the plugin validates that the React Router 'basename' is compatible with Vite's 'base' option: if base is set and basename is not '/', basename must start with base. The default Vite dev server serves all assets and the app under 'base', so a basename without that prefix would route to paths the dev server can never reach.","triggerScenarios":"Running 'react-router dev' with vite.config.ts base: \"/my-app/\" and react-router.config.ts basename: \"/dashboard\" — basename is set, non-'/', does not start with base, and the dev server is the default (non-middlewareMode) one.","commonSituations":"Deploying under a subpath (GitHub Pages, shared hosting) and setting both vite base and router basename independently; migrating an app that only used basename and later adding vite base; RSC Framework templates combined with a repo subpath.","solutions":["Prefix basename with base, e.g. base \"/my-app/\" + basename \"/my-app/dashboard\"","Drop the React Router basename and let vite base drive the prefix alone","Run dev through a custom server or Vite middlewareMode, where this default-dev-server constraint does not apply"],"exampleFix":"// before\n// vite.config.ts\nexport default defineConfig({ base: \"/my-app/\" });\n// react-router.config.ts\nexport default { basename: \"/dashboard\" };\n\n// after\n// react-router.config.ts\nexport default { basename: \"/my-app/dashboard\" };","handlingStrategy":"validation","validationCode":"// fail fast before starting the dev server\nconst viteBase = \"/my-app/\";          // value from vite.config.ts\nconst basename = \"/my-app/dashboard\"; // value from react-router.config.ts\nif (viteBase && basename !== \"/\" && !basename.startsWith(viteBase)) {\n  throw new Error(`basename '${basename}' must start with vite base '${viteBase}' in dev`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive basename from base in one place (e.g. basename: `${base}app`) so they can't drift","Document the base/basename relationship in the repo README for new contributors","Prefer relying on vite base alone unless basename is truly required"],"tags":["vite","basename","base","dev-server","rsc","config"],"backgroundTag":"base-path-mismatch","analyzedSha":"6beaca39526d5716c3c112ebb0782765baa5a9ce","analyzedAt":"2026-08-18T18:04:14.938Z","contentChangedAt":"2026-08-18T18:04:14.938Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}