Updating from v7 | React Router

We try our best to keep major version upgrades simple and boring through the use of opt-in APIs and Future Flags. Future flags are used to gate breaking changes that don't otherwise have a good call-site opt-in strategy. By adopting all opt-in APIs and future flags while still on v7, you should be able to update to React Router v8 with minimal changes.
We highly recommend you make a commit after each step and ship it instead of doing everything all at once. Most flags can be adopted in any order, with exceptions noted below.
React Router v8 requires the following minimum versions. Update them before updating React Router to v8:
Framework mode also requires:
Before adopting any future flags or call-site opt-in changes, update to the latest minor version of v7.x to make sure you have access to the latest flags. You may see a number of deprecation warnings as you upgrade, which we'll cover below.
👉 Update to latest v7
Middleware allows you to run code before and after the Response generation for the matched path. This enables common patterns like authentication, logging, error handling, and data preprocessing in a reusable way. Please see the docs for more information.
If you're using the context parameter in loader and action functions, you may need to update your code:
This feature enables splitting client-side route exports (clientLoader, clientAction, clientMiddleware, HydrateFallback) into separate chunks that can be loaded independently from the route component. This allows these exports to be fetched and executed while the component code is still downloading, improving performance for client-side data loading.
This can be set to true for opt-in behavior, or "enforce" to require all routes to be splittable (which will cause build failures for routes that cannot be split due to shared code).
No code changes are required. This is an optimization feature that works automatically once enabled.
This enables support for the experimental Vite Environment API, which provides a more flexible and powerful way to configure Vite environments. This is only available when using Vite 6+.
Most users won't need to make any changes. However, if you have custom Vite configuration that previously relied on the isSsrBuild flag — such as a custom server build that sets build.rollupOptions.input — you'll need to move that configuration under the per-environment Environment API config instead.
For example, a custom server build should move its SSR rollupOptions from the top-level build config into environments.ssr.build:
See the node-custom-server template for a complete example.
By default, React Router normalizes the request.url passed to your loader, action, and middleware functions by removing React Router's internal implementation details. Specifically, it removes .data suffixes and internal search parameters like ?index and ?_routes.
This flag eliminates that normalization and passes the raw HTTP request instance to your handlers. This provides a few benefits:
If you were previously relying on the normalization of request.url, you can switch to use the new sibling url parameter which contains a URL instance with React Router's internal implementation details removed.
If your code relies on inspecting the request URL, you should review it for any assumptions about the URL format:
React Router serves Framework mode data requests from .data URLs. Previously, data requests for routes with and without trailing slashes could map to the same .data URL because trailing slashes were not considered during URL generation. This flag preserves trailing slash semantics for data request URLs to avoid ambiguity when your app distinguishes between trailing-slash and non-trailing-slash URLs.
In v7, your HTTP and request pathnames are as follows for /a/b/c and /a/b/c/
With this flag enabled, these pathnames are made consistent through a new _.data format for client-side .data requests:
This flag also aligns the root data request to match this behavior by changing it from /_root.data to /_.data.
If you have custom app, CDN, cache, or rewrite logic that matches .data request URLs, update it to handle the new trailing-slash-aware /_.data format.
The changes in this section are not controlled by future flags, but you can update your code while still on v7 before moving to v8.
React Router v8 removed deprecated data fields in favor of loaderData in a few places:
Use loaderData instead on MetaArgs, each item in MetaArgs.matches, and each match returned from useMatches()
Replace data with loaderData in your meta functions:
If you read data from parent matches, update those references too:
Replace data with loaderData on useMatches() calls:
React Router v8 removes the react-router-dom re-export package. In v8, you should import DOM-specific APIs from react-router/dom and everything else from react-router.
Uninstall react-router-dom:
Replace react-router-dom imports with react-router imports:
For DOM-specific APIs, import from react-router/dom:
React Router v8 removes the React Router Cloudflare dev proxy. Cloudflare projects should use @cloudflare/vite-plugin instead.
Replace cloudflareDevProxy with cloudflare:
In v7, the @react-router/architect adapter uses X-Forwarded-Host when creating the request, falling back to the Host header. In React Router v8, the adapter uses event.requestContext.domainName by default, falling back to the Host header.
Opt in to the v8 behavior while still on v7 by passing useRequestContextDomainName: true:
This option is removed in v8 because the event.requestContext.domainName behavior is the default.
Now that your app is caught up, update to v8: