Migration and Pitfalls

Pick Your Path

Two rules make every one of these boring. Do one hop at a time, and turn on every future flag on the version you already run before bumping the major. The flag system exists so the major itself ships no new behavior.

v7 to v8

All future.v8_* flags were removed and their behavior is the default. Adopt them one at a time on v7.x, then upgrade.

Other breaking changes in v8.0.0:

- react-router-dom is gone. Import from react-router, except RouterProvider and HydratedRouter which come from react-router/dom. - meta data removed. Use loaderData on MetaArgs, MetaMatch, UIMatch, and Route.ComponentProps.matches. - AppLoadContext removed. A custom server's getLoadContext must return a RouterContextProvider, not a plain object. - Cloudflare dev proxy removed. Use @cloudflare/vite-plugin. - hasErrorBoundary removed from RouteObject, <Route> props, and lazy definitions. The router infers it. - Baseline moved. Node 22.22.0+, React 19.2.7+, Vite 7+, ESM only.

npm i react-router@8
npm i -D @react-router/dev@8
npx react-router typegen && npx tsc   # find the type fallout first

v6 to v7

Mostly mechanical. The package rename is a find and replace.

# GNU sed, Linux
find ./src \( -name "*.ts" -o -name "*.tsx" \) -type f \
  -exec sed -i 's|from "react-router-dom"|from "react-router"|g' {} +

# BSD sed, macOS, note the empty -i argument
find ./src \( -name "*.ts" -o -name "*.tsx" \) -type f \
  -exec sed -i '' 's|from "react-router-dom"|from "react-router"|g' {} +

Turn on all of these on v6.x first, fix what breaks, then bump.

Remix v2 to v7

Remix v2 and v7 Framework mode are the same runtime, so this is a rename plus a config move.

Then swap the Vite plugin from vitePlugin as remix to reactRouter, add app/routes.ts and react-router.config.ts, and rename the entry file components (RemixServer becomes ServerRouter, RemixBrowser becomes HydratedRouter).

Library Mode to Framework Mode

Both starting points converge on the same result. This one needs judgment, not a codemod, so migrate route by route.

1. Install @react-router/dev and add reactRouter() to vite.config.ts. 2. Add react-router.config.ts with ssr: false so nothing has to move to the server on day one. 3. Add app/root.tsx with the Layout export, <Meta />, <Links />, <Scripts />, and <ScrollRestoration />. 4. Add app/routes.ts. From createBrowserRouter, translate the route objects. From <Routes> and <Route>, translate the JSX tree. 5. Delete the old createRoot call. The plugin owns the entry now. 6. Convert routes one at a time: element becomes the default export, loader and action become exports, errorElement becomes ErrorBoundary, hydrateFallbackElement becomes HydrateFallback. 7. Flip ssr: true when you are ready, and move each clientLoader that can run on the server to a loader.

Step 7 is the judgment call. Anything touching window, localStorage, or a browser only SDK stays in a clientLoader or moves into a useEffect, or SSR crashes on the first render.

Pitfalls