UNPKG

6.69 kB Markdown View Raw
1---
2title: Future Changes
3order: 1
4---
5
6# Future Changes
7
8We try our best to keep major version upgrades simple and boring through the use of opt-in APIs and [Future Flags][api-development-strategy]. 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, you should be able to upgrade to the next major version of React Router with minimal changes.
9
10We plan to ship new major versions roughly once a year as described in our [Open Governance Model][governance], so this guide will continue to track future changes you can adopt ahead of the next major release. v9 is currently estimated for mid-2027 when Node 22 reaches EOL.
11
12We 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.
13
14<docs-info>This is an evolving document that will be updated throughout the duration of v8</docs-info>
15
16## Minimum Versions
17
18[MODES: framework, data, declarative]
19
20React Router v9 will require the following minimum versions (as of now). You can prepare for the upgrade by updating them while still on v8:
21
22- `node@24+`
23
24## Update to latest v8.x
25
26Before adopting any future flags or call-site opt-in changes, you should update to the latest minor version of v8.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.
27
28👉 Update to latest v8
29
30```sh
31npm install react-router@8 @react-router/{dev,node,etc.}@8
32```
33
34## Future Flags
35
36_No future flags yet_
37
38## Other Planned Breaking Changes
39
40_No known planned breaking changes yet_
41
42## Unstable Future Flags (Optional)
43
44We document some [unstable] flags here as a reference for folks contributing to the project via beta testing, but they are not generally recommended for production use and may have breaking changes in patch or minor releases - adopt with caution!
45
46### `future.unstable_enableNodeReadableStream`
47
48[MODES: framework]
49
50**Background**
51
52Now that the Web Streams API is [stable](https://nodejs.org/docs/latest-v22.x/api/webstreams.html) in Node 22+, it's viable for React Router to use React's [`renderToReadableStream`](https://react.dev/reference/react-dom/server/renderToReadableStream) in the server entry.
53
54When no `entry.server.tsx` file is present, React Router defaults to [`renderToPipeableStream`](https://react.dev/reference/react-dom/server/renderToPipeableStream) when a Node runtime is detected, and `renderToReadableStream` otherwise.
55
56With this flag enabled, React Router will default to `renderToReadableStream` on all runtimes, including Node. You can continue to use `renderToPipeableStream` via a custom `entry.server.tsx` file if needed.
57
58<docs-info>Enabling this flag might even provide slight performance gains because we are already using Web Streams internally, so this flag removes some unnecessary transforms between Web and Node streams.</docs-info>
59
60👉 **Enable the Flag**
61
62```ts filename=react-router.config.ts
63import type { Config } from "@react-router/dev/config";
64
65export default {
66 future: {
67 unstable_enableNodeReadableStream: true,
68 },
69} satisfies Config;
70```
71
72**Update your Code**
73
74No code changes are required. If your app has a custom `entry.server.tsx`, this flag will not change your runtime behavior.
75
76### `future.unstable_optimizeDeps`
77
78[MODES: framework]
79
80**Background**
81
82This flag lets React Router provide Vite's dependency optimizer with the client entry file and route module files. This can improve dependency optimization in development, but the behavior is still experimental.
83
84👉 **Enable the Flag**
85
86```ts filename=react-router.config.ts
87import type { Config } from "@react-router/dev/config";
88
89export default {
90 future: {
91 unstable_optimizeDeps: true,
92 },
93} satisfies Config;
94```
95
96**Update your Code**
97
98No code changes are required. If you run into dependency optimization issues after enabling this flag, remove the flag and restart the dev server.
99
100### `future.unstable_routePatternMatching`
101
102[MODES: data]
103
104**Background**
105
106This flag opts Data Routers into a new (and vastly more efficient) route matcher
107powered by [`@remix-run/route-pattern`](https://github.com/remix-run/remix/tree/main/packages/route-pattern).
108It supports the existing React Router path syntax and matching behavior, but may
109rank _slightly_ differently in some cases - please read the section below on
110potential ranking differences.
111
112👉 **Preload the Matcher and Enable the Flag**
113
114```ts
115import { createBrowserRouter } from "react-router";
116import { unstable_preloadRoutePattern } from "react-router/route-pattern";
117
118unstable_preloadRoutePattern();
119
120const router = createBrowserRouter(routes, {
121 future: {
122 unstable_routePatternMatching: true,
123 },
124});
125```
126
127The `react-router/route-pattern` sub-export statically imports the new matcher
128implementation. Tree-shaking bundlers remove it from applications that do not
129use the preload function. You must call the function before creating a router
130with the flag enabled - router creation will throw if the matcher has not been
131initialized. Initialization is synchronous, and repeated calls are safe.
132
133**Update your Code**
134
135No route configuration changes are required, but you should review any routes with
136overlapping patterns to ensure the new ranking behavior selects the intended route.
137The new implementation matches by positional specificity instead of aggregate
138segment scores. This means a route with a longer static prefix can rank above a
139route with more dynamic segments.
140
141For example, both of these routes match `/products/one/two/three`:
142
143```ts
144const routes = [
145 { path: "/products/*", id: "products" },
146 {
147 path: "/:first/:second/:third/:fourth",
148 id: "segments",
149 },
150];
151```
152
153The legacy matcher selects `segments` based on its aggregate segment score. The
154new matcher selects `products` because its static `products` segment is more
155specific than the dynamic `:first` segment in the same position.
156
157Once you enable this flag, use the `router.match()` when you need to match a
158location (this is currently marked private and will become stable at the same
159time this flag stabilizes). Standalone matching APIs such as `matchRoutes`,
160`matchPath`, and `useMatch` continue to use the legacy matcher and may return
161different matches than the router.
162
163Case-sensitive routes are not currently supported with this flag.
164
165[api-development-strategy]: ../community/api-development-strategy
166[governance]: https://github.com/remix-run/react-router/blob/main/GOVERNANCE.md#design-goals
167[unstable]: ../community/api-development-strategy#unstable-flags