react-router 8.1.0 → 8.3.0

package/docs/start/framework/route-module.md

@@ -500,27 +500,27 @@ export function shouldRevalidate(
 
 When using [SPA Mode][spa-mode], there are no server loaders to call on navigations, so `shouldRevalidate` behaves the same as it does in [Data Mode][data-mode-should-revalidate].
 
-[`ShouldRevalidateFunctionArgs` Reference Documentation ↗](https://api.reactrouter.com/v7/interfaces/react-router.ShouldRevalidateFunctionArgs.html)
+[`ShouldRevalidateFunctionArgs` Reference Documentation ↗](https://api.reactrouter.com/v8/interfaces/react-router.ShouldRevalidateFunctionArgs.html)
 
 ---
 
 Next: [Rendering Strategies](./rendering)
 
-[middleware-params]: https://api.reactrouter.com/v7/types/react-router.MiddlewareFunction.html
+[middleware-params]: https://api.reactrouter.com/v8/types/react-router.MiddlewareFunction.html
 [middleware]: ../../how-to/middleware
 [when-middleware-runs]: ../../how-to/middleware#when-middleware-runs
-[loader-params]: https://api.reactrouter.com/v7/interfaces/react-router.LoaderFunctionArgs
-[client-loader-params]: https://api.reactrouter.com/v7/types/react-router.ClientLoaderFunctionArgs
-[action-params]: https://api.reactrouter.com/v7/interfaces/react-router.ActionFunctionArgs
-[client-action-params]: https://api.reactrouter.com/v7/types/react-router.ClientActionFunctionArgs
+[loader-params]: https://api.reactrouter.com/v8/interfaces/react-router.LoaderFunctionArgs
+[client-loader-params]: https://api.reactrouter.com/v8/types/react-router.ClientLoaderFunctionArgs
+[action-params]: https://api.reactrouter.com/v8/interfaces/react-router.ActionFunctionArgs
+[client-action-params]: https://api.reactrouter.com/v8/types/react-router.ClientActionFunctionArgs
 [use-route-error]: ../../api/hooks/useRouteError
 [is-route-error-response]: ../../api/utils/isRouteErrorResponse
 [headers]: https://developer.mozilla.org/en-US/docs/Web/API/Response/headers
 [use-matches]: ../../api/hooks/useMatches
 [link-element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link
 [meta-element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
-[meta-params]: https://api.reactrouter.com/v7/interfaces/react-router.MetaArgs
-[meta-function]: https://api.reactrouter.com/v7/types/react-router.MetaDescriptor.html
+[meta-params]: https://api.reactrouter.com/v8/interfaces/react-router.MetaArgs
+[meta-function]: https://api.reactrouter.com/v8/types/react-router.MetaDescriptor.html
 [data-mode-should-revalidate]: ../data/route-object#shouldrevalidate
 [spa-mode]: ../../how-to/spa
 [client-data]: ../../how-to/client-data

package/docs/start/framework/routing.md

@@ -359,4 +359,4 @@ Note that these routes do not participate in data loading, actions, code splitti
 Next: [Route Module](./route-module)
 
 [file-route-conventions]: ../../how-to/file-route-conventions
-[outlet]: https://api.reactrouter.com/v7/functions/react-router.Outlet.html
+[outlet]: https://api.reactrouter.com/v8/functions/react-router.Outlet.html

package/docs/upgrading/component-routes.md

@@ -49,7 +49,7 @@ npm install @react-router/node
 
 **👉 Swap out the React plugin for React Router.**
 
-```diff filename=vite.config.ts
+```tsx diff filename=vite.config.ts
 -import react from '@vitejs/plugin-react'
 +import { reactRouter } from "@react-router/dev/vite";
 import { defineConfig } from "vite";

package/docs/upgrading/future.md

@@ -46,6 +46,39 @@ _No known planned breaking changes yet_
 
 We 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!
 
+### `future.unstable_enableNodeReadableStream`
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+**Background**
+
+Now 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.
+
+When 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.
+
+With 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.
+
+<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>
+
+👉 **Enable the Flag**
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  future: {
+    unstable_enableNodeReadableStream: true,
+  },
+} satisfies Config;
+```
+
+**Update your Code**
+
+No code changes are required. If your app has a custom `entry.server.tsx`, this flag will not change your runtime behavior.
+
 ### `future.unstable_optimizeDeps`
 
 [MODES: framework]

package/docs/upgrading/router-provider.md

@@ -85,7 +85,7 @@ Instead of importing your route modules directly, lazy load and convert them to
 
 Not only does your route definition now conform to the Route Module API, but you also get the benefits of code-splitting your routes.
 
-```diff filename=src/main.tsx
+```tsx diff filename=src/main.tsx
 let router = createBrowserRouter([
   // ... other routes
   {
@@ -120,7 +120,7 @@ npm install @react-router/node
 
 **👉 Swap out the React plugin for React Router**
 
-```diff filename=vite.config.ts
+```tsx diff filename=vite.config.ts
 -import react from '@vitejs/plugin-react'
 +import { reactRouter } from "@react-router/dev/vite";
 import { defineConfig } from "vite";
@@ -247,7 +247,7 @@ export default function App() {
 
 You would move everything above the `RouterProvider` into `root.tsx`.
 
-```diff filename=src/root.tsx
+```tsx diff filename=src/root.tsx
 +import "./index.css";
 
 // ... other imports and Layout
@@ -326,7 +326,7 @@ touch src/routes.ts src/catchall.tsx
 
 Move your route definitions to `routes.ts`. Note that the schemas don't match exactly, so you will get type errors; we'll fix this next.
 
-```diff filename=src/routes.ts
+```tsx diff filename=src/routes.ts
 +import type { RouteConfig } from "@react-router/dev/routes";
 
 -const router = createBrowserRouter([
@@ -362,7 +362,7 @@ Move your route definitions to `routes.ts`. Note that the schemas don't match ex
 
 **👉 Replace the `lazy` loader with a `file` loader**
 
-```diff filename=src/routes.ts
+```tsx diff filename=src/routes.ts
 export default [
   {
     path: "/",

package/docs/upgrading/v7.md

@@ -5,7 +5,7 @@ order: 2
 
 # Upgrading from v7
 
-We 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.
+We 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 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.
 
@@ -16,19 +16,19 @@ We highly recommend you make a commit after each step and ship it instead of doi
 <br/>
 <br/>
 
-React Router v8 requires the following minimum versions. You can prepare for the upgrade by updating them while still on v7:
+React Router v8 requires the following minimum versions. Update them before updating React Router to v8:
 
 - `node@22.22+`
 - `react@19.2.7+`/`react-dom@19.2.7+`
 
-Framework mode will also require:
+Framework mode also requires:
 
 - `vite@7+` (requires `future.v8_viteEnvironmentApi`)
   - also make sure any custom Vite plugins or config are compatible with Vite 7
 
 ## Update to latest v7.x
 
-Before adopting any future flags or call-site opt-in changes, you should 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.
+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
 
@@ -140,7 +140,7 @@ Most users won't need to make any changes. However, if you have custom Vite conf
 
 For example, a custom server build should move its SSR `rollupOptions` from the top-level `build` config into `environments.ssr.build`:
 
-```diff filename=vite.config.ts
+```tsx diff filename=vite.config.ts
 import { reactRouter } from "@react-router/dev/vite";
 import { defineConfig } from "vite";
 
@@ -243,7 +243,7 @@ export async function loader({
 
 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.
 
-Currently, your HTTP and `request` pathnames would be as follows for `/a/b/c` and `/a/b/c/`
+In v7, your HTTP and `request` pathnames are as follows for `/a/b/c` and `/a/b/c/`
 
 | URL `/a/b/c` | **HTTP pathname** | **`request` pathname`** |
 | ------------ | ----------------- | ----------------------- |
@@ -255,7 +255,7 @@ Currently, your HTTP and `request` pathnames would be as follows for `/a/b/c` an
 | **Document**  | `/a/b/c/`         | `/a/b/c/` ✅            |
 | **Data**      | `/a/b/c.data`     | `/a/b/c` ⚠️             |
 
-With this flag enabled, these pathnames will be made consistent though a new `_.data` format for client-side `.data` requests:
+With this flag enabled, these pathnames are made consistent through a new `_.data` format for client-side `.data` requests:
 
 | URL `/a/b/c` | **HTTP pathname** | **`request` pathname`** |
 | ------------ | ----------------- | ----------------------- |
@@ -285,11 +285,11 @@ export default {
 
 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.
 
-## Other Planned Breaking Changes
+## Other Breaking Changes
 
-The changes in this section are not controlled by future flags, but you can update your code in v7 to be ready for v8.
+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.
 
-### `meta` `data` Argument
+### `meta`/`matches` `data` Values
 
 [MODES: framework]
 
@@ -298,13 +298,19 @@ The changes in this section are not controlled by future flags, but you can upda
 
 **Background**
 
-The `data` fields passed to route module `meta` functions are deprecated and will be removed in React Router v8. Use `loaderData` instead on `MetaArgs` and each item in `MetaArgs.matches`.
+React Router v8 removed deprecated `data` fields in favor of `loaderData` in a few places:
+
+- `meta` function `data` argument
+- `meta` function `matches` argument (`matches[i].data`)
+- `useMatches()` (`matches[i].data`)
+
+Use `loaderData` instead on `MetaArgs`, each item in `MetaArgs.matches`, and each match returned from `useMatches()`
 
 👉 **Update your Code**
 
 Replace `data` with `loaderData` in your `meta` functions:
 
-```diff
+```tsx diff
 export function meta({
 -  data,
 +  loaderData,
@@ -321,7 +327,7 @@ export function meta({
 
 If you read data from parent matches, update those references too:
 
-```diff
+```tsx diff
 export function meta({ matches }: Route.MetaArgs) {
   let rootMatch = matches.find((match) => match.id === "root");
 -  let rootData = rootMatch?.data;
@@ -331,6 +337,17 @@ export function meta({ matches }: Route.MetaArgs) {
 }
 ```
 
+Replace `data` with `loaderData` on `useMatches()` calls:
+
+```tsx diff
+export default function Component({ matches, loaderData }: ComponentProps) {
+  let matches = useMatches();
+- const rootLoaderData = matches[0].data;
++ const rootLoaderData = matches[0].loaderData;
+  // ...
+}
+```
+
 ### `react-router-dom`
 
 [MODES: framework, data, declarative]
@@ -340,7 +357,7 @@ export function meta({ matches }: Route.MetaArgs) {
 
 **Background**
 
-React Router v8 will remove 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`.
+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`.
 
 👉 **Update your Code**
 
@@ -352,14 +369,14 @@ npm uninstall react-router-dom
 
 Replace `react-router-dom` imports with `react-router` imports:
 
-```diff
+```tsx diff
 -import { Link, useLocation } from "react-router-dom";
 +import { Link, useLocation } from "react-router";
 ```
 
 For DOM-specific APIs, import from `react-router/dom`:
 
-```diff
+```tsx diff
 -import { RouterProvider } from "react-router-dom";
 +import { RouterProvider } from "react-router/dom";
 ```
@@ -373,13 +390,13 @@ For DOM-specific APIs, import from `react-router/dom`:
 
 **Background**
 
-React Router v8 will remove the React Router Cloudflare dev proxy. Cloudflare projects should use [`@cloudflare/vite-plugin`][cloudflare-vite-plugin] instead.
+React Router v8 removes the React Router Cloudflare dev proxy. Cloudflare projects should use [`@cloudflare/vite-plugin`][cloudflare-vite-plugin] instead.
 
 👉 **Update your Code**
 
 Replace `cloudflareDevProxy` with `cloudflare`:
 
-```diff filename=vite.config.ts
+```tsx diff filename=vite.config.ts
 import { reactRouter } from "@react-router/dev/vite";
 -import { cloudflareDevProxy } from "@react-router/dev/vite/cloudflare";
 +import { cloudflare } from "@cloudflare/vite-plugin";
@@ -403,11 +420,11 @@ export default defineConfig({
 
 **Background**
 
-The `@react-router/architect` adapter currently uses `X-Forwarded-Host` when creating the `request`, falling back to the `Host` header. In React Router v8, the adapter will use `event.requestContext.domainName` by default, falling back to the `Host` header.
+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.
 
 👉 **Update your Code**
 
-Opt in to the v8 behavior now by passing `useRequestContextDomainName: true`:
+Opt in to the v8 behavior while still on v7 by passing `useRequestContextDomainName: true`:
 
 ```ts
 import { createRequestHandler } from "@react-router/architect";
@@ -419,11 +436,11 @@ export const handler = createRequestHandler({
 });
 ```
 
-This option will be removed in v8 once the `event.requestContext.domainName` behavior is the default.
+This option is removed in v8 because the `event.requestContext.domainName` behavior is the default.
 
 ## Upgrade to v8
 
-Now that your app is caught up, you can simply update to v8 (theoretically!) without issue.
+Now that your app is caught up, update to v8:
 
 ```shellscript nonumber
 # data/declarative mode

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-router",
   "type": "module",
-  "version": "8.1.0",
+  "version": "8.3.0",
   "description": "Declarative routing for React",
   "keywords": [
     "react",