React router 8 importing @react-router/dev/routes in production build

[ShahriarKh]

I want to deploy a react router 8 app with docker. This is my package.json (showing only react router's related stuff)

{
 "scripts": {
    "build": "react-router build",
    "start": "react-router-serve ./build/server/index.js",
  },
 "dependencies": {
    "@react-router/node": "^8.4.0",
    "@react-router/serve": "^8.4.0",
    "react-router": "^8.4.0",
    "react": "^19.3.0",
    "react-dom": "^19.3.0",
  },
  "devDependencies": {
    "@react-router/dev": "^8.4.0",
    "@tailwindcss/vite": "^4.3.3",
    "typescript": "^7.0.2",
    "vite": "^8.3.0"
  },
}

My react-router.config.ts:

import type { Config } from '@react-router/dev/config';

export default {
  ssr: true,
} satisfies Config;

and my vite.config.ts:

import { reactRouter } from '@react-router/dev/vite';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  resolve: {
    tsconfigPaths: true,
  },
  plugins: [tailwindcss(), reactRouter()],
});

Everything is very similar to the official template https://github.com/remix-run/react-router-templates/tree/main/default

Both the official template and I are omitting development dependencies from the final image. They do npm ci --omit=dev and I run npm prune --omit=dev after build. I am kinda sure that they both result in the same thing, and I am doing the latter just to save some bandwidth... Anyway, this doesn't seem to be the original problem. The broken thing is that react router docs explicitly says:

The React Router CLI comes from the @react-router/dev package. Make sure it is in your package.json devDependencies so it doesn't get deployed to your server.

But the built file imports it (!):

# build/server/index.js
...
import { index, layout, prefix, route } from "@react-router/dev/routes";
...

A quick fix will be adding @react-router/dev to dependencies rather than devDependencies (or stop pruning dev deps from final build, because build works locally when all packages are available). But this feels illegal, and I don't want to fix it that way.

Is it a bug in react-router (& is it supposed to convert routes and use another package?), or it's the documentation being misleading, or is it me using the package wrongly?

To give more context, I have many routes.ts files using this pattern:

import { index, layout, prefix, route } from '@react-router/dev/routes';

export const settings = [
  ...prefix('settings', [
    layout('./settings/layout.tsx', [
      index('./settings/page.tsx'),
      route('app', './settings/app/page.tsx'),
    ]),
  ]),
];

Also asked in StackOverflow, but as you know, their routine is hitting the downvote button instead of being helpful 🙃

[widechaos]

I'd keep @react-router/dev in devDependencies and check whether a runtime module imports one of your route-config files, directly or through a barrel export.

Splitting the configuration across files is fine. In Framework Mode, the route configuration describes which route modules to build. A loader, component, or other runtime module importing that configuration introduces a separate dependency on the helpers used to construct it.

I tested a small app with React Router / @react-router/dev 8.4.0, Vite 8.3.0 and React 19.3.0:

• app/routes.ts imported a separate settings config using index() and prefix(). The server build had no @react-router/dev/routes import and loaded successfully after npm prune --omit=dev.
• Adding a loader that imported and read that same settings array put import { index, prefix } from "@react-router/dev/routes" into the server build. After pruning, loading it failed with ERR_MODULE_NOT_FOUND for @react-router/dev.

If you share route information with navigation components or loaders, move the runtime URLs/metadata into a separate module that doesn't import @react-router/dev/routes. Keep the configuration arrays on the build-time side of that boundary. Also check broad import.meta.glob patterns and barrel exports that might pull those files in.

This reproduces one way to get your symptom; I haven't established that it's the cause in your app. Could you share the top-level app/routes.ts and any imports of the split config files outside it? If they're used only by the route configuration, a minimal reproduction would help distinguish a build bug from an application import.

[ShahriarKh]

Thank you for your detailed response.
Yes, it was something being exported in the same file where @react-router/dev/routes was imported. Moving that to a separate file fixed the issue.

import { prefix, route } from '@react-router/dev/routes';

export const somePages = [
  ...prefix('page-prefix', [
    route('page-route', './path/to/component.tsx'),
  ]),
];

- export const routeNames: Record<string: string> = { 'page-route': 'Page Route' }