Upgrading from Remix

React Router v7 is the next major version of Remix after v2 (see our "Incremental Path to React 19" blog post) for more information).

The Remix v2 -> React Router v7 upgrade requires mostly updates to dependencies if you are caught up on all Remix v2 future flags (step 1).

1. Adopt future flags

👉 Adopt future flags

Adopt all existing future flags in your Remix v2 application.

2. Update dependencies

Most of the "shared" APIs that used to be re-exported through the runtime-specific packages (@remix-run/node, @remix-run/cloudflare, etc.) have all been collapsed into react-router in v7. So instead of importing from @react-router/node or @react-router/cloudflare, you'll import those directly from react-router.

-import { redirect } from "@react-router/node";
+import { redirect } from "react-router";

The only APIs you should be importing from the runtime-specific packages in v7 are APIs that are specific to that runtime, such as createFileSessionStorage for Node and createWorkersKVSessionStorage for Cloudflare.

👉 Run the codemod (automated)

You can automatically update your packages and imports with the following codemod. This codemod updates all of your packages and imports. Be sure to commit any pending changes before running the codemod, in case you need to revert.

npx codemod remix/2/react-router/upgrade

👉 Install the new dependencies

After the codemod updates your dependencies, you need to install the dependencies to remove Remix packages and add the new React Router packages.

npm install

👉 Update your dependencies (manual)

If you prefer not to use the codemod, you can manually update your dependencies.

3. Change scripts in package.json

👉 Update the scripts in your package.json

4. Add a routes.ts file

In React Router v7 you define your routes using the app/routes.ts file. View the routing documentation for more information.

👉 Update dependencies (if using Remix v2 unstable_routeConfig flag)

// app/routes.ts
-import { type RouteConfig } from "@remix-run/route-config";
-import { flatRoutes } from "@remix-run/fs-routes";
-import { remixRoutesOptionAdapter } from "@remix-run/routes-option-adapter";
+import { type RouteConfig } from "@react-router/dev/routes";
+import { flatRoutes } from "@react-router/fs-routes";
+import { remixRoutesOptionAdapter } from "@react-router/remix-routes-option-adapter";

export default [
  // however your routes are defined
] satisfies RouteConfig;

👉 Add a routes.ts file (if not using Remix v2 unstable_routeConfig flag)

touch app/routes.ts

For backwards-compatibility and for folks who prefer file-based conventions, you can opt-into the same "flat routes" convention you are using in Remix v2 via the new @react-router/fs-routes package:

import { type RouteConfig } from "@react-router/dev/routes";
import { flatRoutes } from "@react-router/fs-routes";

export default flatRoutes() satisfies RouteConfig;

Or, if you were using the routes option to define config-based routes:

import { type RouteConfig } from "@react-router/dev/routes";
import { remixRoutesOptionAdapter } from "@react-router/remix-routes-option-adapter";

export default remixRoutesOptionAdapter((defineRoutes) => {
  return defineRoutes((route) => {
    route("/", "home/route.tsx", { index: true });
    route("about", "about/route.tsx");
    route("", "concerts/layout.tsx", () => {
      route("trending", "concerts/trending.tsx");
      route(":city", "concerts/city.tsx");
    });
  });
}) satisfies RouteConfig;

If you were using the routes option in your vite.config.ts, be sure to remove it.

export default defineConfig({
  plugins: [
    remix({
      ssr: true,
-     ignoredRouteFiles: ['**/*'],
-     routes(defineRoutes) {
-       return defineRoutes((route) => {
-         route("/somewhere/cool/*", "catchall.tsx");
-       });
-     },
    })
    tsconfigPaths(),
  ],
});

5. Add a React Router config

👉 Add react-router.config.ts your project

The config that was previously passed to the remix plugin in vite.config.ts is now exported from react-router.config.ts.

Note: At this point you should remove the v3 future flags you added in step 1.

touch react-router.config.ts

// vite.config.ts
export default defineConfig({
  plugins: [
-   remix({
-     ssr: true,
-     future: {/* all the v3 flags */}
-   }),
+   remix(),
    tsconfigPaths(),
  ],
});

// react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+export default {
+  ssr: true,
+} satisfies Config;

6. Add React Router plugin to vite.config

👉 Add reactRouter plugin to vite.config

Change vite.config.ts to import and use the new reactRouter plugin from @react-router/dev/vite:

-import { vitePlugin as remix } from "@remix-run/dev";
+import { reactRouter } from "@react-router/dev/vite";
import { defineConfig } from "vite";
import tsconfigPaths from "vite-tsconfig-paths";

export default defineConfig({
  plugins: [
-   remix(),
+   reactRouter(),
    tsconfigPaths(),
  ],
});

7. Enable type safety

React Router automatically generates types for your route modules into a .react-router/ directory at the root of your app. This directory is fully managed by React Router and should be gitignore'd. Learn more about the new type safety features.

👉 Add .react-router/ to .gitignore

.react-router/

👉 Update tsconfig.json

Update the types field in your tsconfig.json to include:

• .react-router/types/**/* path in the include field
• The appropriate @react-router/* package in the types field
• rootDirs for simplified relative imports

{
  "include": [
    /* ... */
+   ".react-router/types/**/*"
  ],
  "compilerOptions": {
-   "types": ["@remix-run/node", "vite/client"],
+   "types": ["@react-router/node", "vite/client"],
    /* ... */
+   "rootDirs": [".", "./.react-router/types"]
  }
}

8. Rename components in entry files

If you have an entry.server.tsx and/or an entry.client.tsx file in your application, you will need to update the main components in these files:

-import { RemixServer } from "@remix-run/react";
+import { ServerRouter } from "react-router";

-<RemixServer context={remixContext} url={request.url} />,
+<ServerRouter context={remixContext} url={request.url} />,

-import { RemixBrowser } from "@remix-run/react";
+import { HydratedRouter } from "react-router/dom";

hydrateRoot(
  document,
  <StrictMode>
-   <RemixBrowser />
+   <HydratedRouter />
  </StrictMode>,
);

9. Update types for AppLoadContext

If you were using getLoadContext in your Remix app, then you'll notice that the LoaderFunctionArgs/ActionFunctionArgs types now type the context parameter incorrectly (optional and typed as any). These types accept a generic for the context type but even that still leaves the property as optional because it does not exist in React Router SPA apps.

The proper long term fix is to move to the new Route.LoaderArgs/Route.ActionArgs types from the new typegen in React Router v7.

However, the short-term solution to ease the upgrade is to use TypeScript's module augmentation feature to override the built in LoaderFunctionArgs/ActionFunctionArgs interfaces.

You can do this with the following code in react-router.config.ts (just make sure it gets picked up by your tsconfig.json's include paths):

// Your AppLoadContext used in v2
interface AppLoadContext {
  whatever: string;
}

// Tell v7 the type of the context and that it is non-optional
declare module "react-router" {
  interface LoaderFunctionArgs {
    context: AppLoadContext;
  }
}

This should allow you to upgrade and ship your application on React Router v7, and then you can incrementally migrate routes to the new typegen approach.

Congratulations! You are now on React Router v7. Go ahead and run your application to make sure everything is working as expected.