{"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":"exception","errorClass":"Error","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/1fd704a7dabcbe3ae09d7387b460e6acaba30ec1/packages/react-router-dev/vite/rsc/plugin.ts#L176-L212","documentation":"Thrown in the RSC plugin config hook during `serve` (dev) when both Vite's `base` and React Router's `basename` are set, basename is not '/', the dev server is not in middleware mode, and basename does not start with base. The default Vite dev server serves assets under `base`, so a basename that doesn't include it would break routing/asset resolution.","triggerScenarios":"vite.config.ts sets `base: '/app/'` while react-router.config.ts sets `basename: '/dashboard/'` (or any basename not prefixed by the base). Conditions: viteUserConfig.base truthy, config.basename !== '/', viteCommand === 'serve', no server.middlewareMode, !config.basename.startsWith(viteUserConfig.base).","commonSituations":"Deploying behind a path prefix (base) and also namespacing the app under a different basename. Mismatched trailing slashes (base '/app', basename '/app') where startsWith is technically true but couples are easy to get wrong. Copying a config that worked without base into a subpath deployment.","solutions":["Make React Router `basename` begin with the Vite `base`, e.g. base '/app/' and basename '/app/dashboard'.","Or set basename to '/' (the default) and let base handle the prefix.","Or move the dev server into middleware mode (server.middlewareMode: true) to bypass the default-server constraint.","Double-check trailing slashes — base '/app' and basename '/application' will fail since '/application' does not start with '/app' as intended only if you meant '/app/...'."],"exampleFix":"// react-router.config.ts + vite.config.ts\n// before\n// vite.config.ts: base: '/app/'\n// react-router.config.ts: basename: '/dashboard/'\n// after\n// react-router.config.ts: basename: '/app/dashboard/'","handlingStrategy":"validation","validationCode":"// in a prebuild script\nimport viteUserConfig from './vite.config';\nimport rrConfig from './react-router.config';\nconst base = viteUserConfig.base; const basename = rrConfig.basename;\nif (base && basename && basename !== '/' && !basename.startsWith(base)) {\n  throw new Error(`basename '${basename}' must start with base '${base}'`);\n}","typeGuard":"function basenameCompatibleWithBase(base: string | undefined, basename: string | undefined): boolean {\n  if (!base || !basename || basename === '/') return true;\n  return basename.startsWith(base);\n}","tryCatchPattern":null,"preventionTips":["When deploying under a path prefix, derive basename from base: basename = base + subpath.","Avoid setting basename for subpath deployments unless you also prefix it with base.","Run a quick config sanity script in CI."],"tags":["rsc","config","base","basename","dev-server"],"backgroundTag":null,"analyzedSha":"1fd704a7dabcbe3ae09d7387b460e6acaba30ec1","analyzedAt":"2026-08-12T13:54:57.804Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}