react-router 8.0.0-pre.0 → 8.0.0

package/docs/start/framework/deploying.md

@@ -94,3 +94,7 @@ Netlify maintains their own template for React Router. Checkout the [Netlify Gui
 ### EdgeOne Pages
 
 EdgeOne Pages maintains their own template for React Router. Checkout the [EdgeOne Pages Guide](https://pages.edgeone.ai/document/framework-react-router) for more information.
+
+### DeployHQ
+
+DeployHQ maintains their own guide for deploying React Router to your own server. Checkout the [DeployHQ Guide](https://www.deployhq.com/guides/deploy-react-router-from-github) for more information.

package/docs/start/framework/installation.md

@@ -37,6 +37,5 @@ npx create-react-router@latest --template remix-run/react-router-templates/<temp
 
 Next: [Routing](./routing)
 
-[manual_usage]: ../how-to/manual-usage
 [default-template]: https://github.com/remix-run/react-router-templates/tree/main/default
 [react-router-templates]: https://github.com/remix-run/react-router-templates

package/docs/start/modes.md

@@ -98,7 +98,6 @@ Every mode supports any architecture and deployment target, so the question isn'
 - are considering Next.js, Solid Start, SvelteKit, Astro, TanStack Start, etc. and want to compare
 - just want to build something with React
 - might want to server render, might not
-- are coming from Remix (React Router v7 is the "next version" after Remix v2)
 - are migrating from Next.js
 
 [→ Get Started with Framework Mode](./framework/installation).
@@ -113,7 +112,7 @@ Every mode supports any architecture and deployment target, so the question isn'
 **Use Declarative Mode if you:**
 
 - want to use React Router as simply as possible
-- are coming from v6 and are happy with the `<BrowserRouter>`
+- are coming from earlier React Router versions and are happy with the `<BrowserRouter>`
 - have a data layer that either skips pending states (like local first, background data replication/sync) or has its own abstractions for them
 - are coming from Create React App (you may want to consider framework mode though)
 

package/docs/upgrading/component-routes.md

@@ -28,8 +28,8 @@ The initial setup requires the most work. However, once complete, you can adopt
 
 To use the Vite plugin, your project requires:
 
-- Node.js 20+ (if using Node as your runtime)
-- Vite 5+
+- Node.js 22.22.0+
+- Vite 7+ or Vite 8+
 
 ## 1. Install the Vite plugin
 

package/docs/upgrading/future.md

@@ -1,31 +1,78 @@
 ---
-title: Future Flags
+title: Future Changes
 order: 1
 ---
 
-# Future Flags and Deprecations
+# Future Changes
 
-This guide walks you through the process of adopting future flags in your React Router app. By following this strategy, you will be able to upgrade to the next major version of React Router with minimal changes. To read more about future flags see [API Development Strategy][api-development-strategy].
+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 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.
 
 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.
 
-## Update to latest v7.x
+<docs-info>This is an evolving document that will be updated throughout the duration of v8</docs-info>
+
+## Minimum Versions
+
+[MODES: framework, data, declarative]
+
+<br/>
+<br/>
+
+React Router v9 will require the following minimum versions (as of now). You can prepare for the upgrade by updating them while still on v8:
+
+- `node@24+`
 
-First update to the latest minor version of v7.x to have the latest future flags. You may see a number of deprecation warnings as you upgrade, which we'll cover below.
+## Update to latest v8.x
 
-👉 Update to latest v7
+Before 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.
+
+👉 Update to latest v8
 
 ```sh
-npm install react-router@7 @react-router/{dev,node,etc.}@7
+npm install react-router@8 @react-router/{dev,node,etc.}@8
 ```
 
+## Future Flags
+
+_No future flags yet_
+
+## Other Planned Breaking Changes
+
+_No known planned breaking changes yet_
+
 ## Unstable Future Flags (Optional)
 
-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 having breaking changes patch/minor releases - adopt with caution!
+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_optimizeDeps`
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+**Background**
+
+This 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.
+
+👉 **Enable the Flag**
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  future: {
+    unstable_optimizeDeps: true,
+  },
+} satisfies Config;
+```
+
+**Update your Code**
 
-_No current unstable flags to document_
+No code changes are required. If you run into dependency optimization issues after enabling this flag, remove the flag and restart the dev server.
 
 [api-development-strategy]: ../community/api-development-strategy
+[governance]: https://github.com/remix-run/react-router/blob/main/GOVERNANCE.md#design-goals
 [unstable]: ../community/api-development-strategy#unstable-flags
-[observability]: ../how-to/instrumentation
-[vite-environment]: https://vite.dev/guide/api-environment

package/docs/upgrading/router-provider.md

@@ -26,8 +26,8 @@ The initial setup requires the most work. However, once complete, you can adopt
 
 To use the Vite plugin, your project requires:
 
-- Node.js 20+ (if using Node as your runtime)
-- Vite 5+
+- Node.js 22.22.0+
+- Vite 7+ or Vite 8+
 
 ## 1. Move route definitions into route modules
 
@@ -276,7 +276,10 @@ If your current `src/main.tsx` looks like this:
 ```tsx filename=src/main.tsx
 import React from "react";
 import ReactDOM from "react-dom/client";
-import { BrowserRouter } from "react-router";
+import {
+  createBrowserRouter,
+  RouterProvider,
+} from "react-router";
 import App from "./App";
 
 const router = createBrowserRouter([

package/docs/upgrading/v7.md

@@ -0,0 +1,443 @@
+---
+title: Updating from v7
+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 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.
+
+## Minimum Versions
+
+[MODES: framework, data, declarative]
+
+<br/>
+<br/>
+
+React Router v8 requires the following minimum versions. You can prepare for the upgrade by updating them while still on v7:
+
+- `node@22.22+`
+- `react@19.2.7+`/`react-dom@19.2.7+`
+
+Framework mode will also require:
+
+- `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.
+
+👉 Update to latest v7
+
+```sh
+npm install react-router@7 @react-router/{dev,node,etc.}@7
+```
+
+## Future Flags
+
+### `future.v8_middleware`
+
+[MODES: framework, data]
+
+<br/>
+<br/>
+
+**Background**
+
+Middleware allows you to run code before and after the [`Response`][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](../how-to/middleware) for more information.
+
+👉 **Enable the Flag**
+
+In Framework mode:
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  future: {
+    v8_middleware: true,
+  },
+} satisfies Config;
+```
+
+In Data mode:
+
+```ts
+import { createBrowserRouter } from "react-router";
+
+const router = createBrowserRouter(routes, {
+  future: {
+    v8_middleware: true,
+  },
+});
+```
+
+**Update your Code**
+
+If you're using the `context` parameter in `loader` and `action` functions, you may need to update your code:
+
+- In Framework mode, if you're using `react-router-serve`, you should not need to make any updates. Otherwise, this only applies if you have a custom server with a `getLoadContext` function. Please see the docs on the middleware [`getLoadContext` changes](../how-to/middleware#changes-to-getloadcontextapploadcontext) and the instructions to [migrate to the new API](../how-to/middleware#migration-from-apploadcontext).
+- In Data mode, add the `Future` module augmentation described in the [middleware docs](../how-to/middleware#1-typescript-augment-future-for-loaderaction-context) so `context` is typed correctly.
+
+### `future.v8_splitRouteModules`
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+**Background**
+
+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).
+
+👉 **Enable the Flag**
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  future: {
+    v8_splitRouteModules: true,
+  },
+} satisfies Config;
+```
+
+**Update your Code**
+
+No code changes are required. This is an optimization feature that works automatically once enabled.
+
+### `future.v8_viteEnvironmentApi`
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+**Background**
+
+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+.
+
+👉 **Enable the Flag**
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  future: {
+    v8_viteEnvironmentApi: true,
+  },
+} satisfies Config;
+```
+
+**Update your Code**
+
+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][vite-environment] config instead.
+
+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
+import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+
+-export default defineConfig(({ isSsrBuild }) => ({
+-  build: {
+-    rollupOptions: isSsrBuild
+-      ? {
+-          input: "./server/app.ts",
+-        }
+-      : undefined,
+-  },
++export default defineConfig({
++  environments: {
++    ssr: {
++      build: {
++        rollupOptions: {
++          input: "./server/app.ts",
++        },
++      },
++    },
++  },
+   plugins: [reactRouter()],
+-}));
++});
+```
+
+See the [`node-custom-server` template][node-custom-server-template] for a complete example.
+
+### `future.v8_passThroughRequests`
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+**Background**
+
+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:
+
+- Reduces server-side overhead by eliminating multiple `new Request()` calls on the critical path
+- Allows you to distinguish document from data requests in your handlers based on the presence of a `.data` suffix (useful for [observability] purposes)
+
+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 representing the normalized location.
+
+👉 **Enable the Flag**
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  future: {
+    v8_passThroughRequests: true,
+  },
+} satisfies Config;
+```
+
+**Update your Code**
+
+If your code relies on inspecting the request URL, you should review it for any assumptions about the URL format:
+
+```tsx
+// ❌ Before: assuming no `.data` suffix in `request.url` pathname
+export async function loader({
+  request,
+}: Route.LoaderArgs) {
+  let url = new URL(request.url);
+  if (url.pathname === "/path") {
+    // This check might now behave differently because the request pathname will
+    // contain the `.data` suffix on data requests
+  }
+}
+
+// ✅ After: use `url` for normalized routing logic and `request.url`
+// for raw routing logic
+export async function loader({
+  request,
+  url,
+}: Route.LoaderArgs) {
+  if (url.pathname === "/path") {
+    // This will always have the `.data` suffix stripped
+  }
+
+  // And now you can distinguish between document versus data requests
+  let isDataRequest = new URL(
+    request.url,
+  ).pathname.endsWith(".data");
+}
+```
+
+### `future.v8_trailingSlashAwareDataRequests`
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+**Background**
+
+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/`
+
+| URL `/a/b/c` | **HTTP pathname** | **`request` pathname`** |
+| ------------ | ----------------- | ----------------------- |
+| **Document** | `/a/b/c`          | `/a/b/c` ✅             |
+| **Data**     | `/a/b/c.data`     | `/a/b/c` ✅             |
+
+| URL `/a/b/c/` | **HTTP pathname** | **`request` pathname`** |
+| ------------- | ----------------- | ----------------------- |
+| **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:
+
+| URL `/a/b/c` | **HTTP pathname** | **`request` pathname`** |
+| ------------ | ----------------- | ----------------------- |
+| **Document** | `/a/b/c`          | `/a/b/c` ✅             |
+| **Data**     | `/a/b/c.data`     | `/a/b/c` ✅             |
+
+| URL `/a/b/c/` | **HTTP pathname**  | **`request` pathname`** |
+| ------------- | ------------------ | ----------------------- |
+| **Document**  | `/a/b/c/`          | `/a/b/c/` ✅            |
+| **Data**      | `/a/b/c/_.data` ⬅️ | `/a/b/c/` ✅            |
+
+This flag also aligns the root data request to match this behavior by changing it from `/_root.data` to `/_.data`.
+
+👉 **Enable the Flag**
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  future: {
+    v8_trailingSlashAwareDataRequests: true,
+  },
+} satisfies Config;
+```
+
+**Update your Code**
+
+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
+
+The changes in this section are not controlled by future flags, but you can update your code in v7 to be ready for v8.
+
+### `meta` `data` Argument
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+**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`.
+
+👉 **Update your Code**
+
+Replace `data` with `loaderData` in your `meta` functions:
+
+```diff
+export function meta({
+-  data,
++  loaderData,
+  matches,
+}: Route.MetaArgs) {
+  return [
+    {
+-      title: data.title,
++      title: loaderData.title,
+    },
+  ];
+}
+```
+
+If you read data from parent matches, update those references too:
+
+```diff
+export function meta({ matches }: Route.MetaArgs) {
+  let rootMatch = matches.find((match) => match.id === "root");
+-  let rootData = rootMatch?.data;
++  let rootData = rootMatch?.loaderData;
+
+  return [{ title: rootData?.siteTitle }];
+}
+```
+
+### `react-router-dom`
+
+[MODES: framework, data, declarative]
+
+<br/>
+<br/>
+
+**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`.
+
+👉 **Update your Code**
+
+Uninstall `react-router-dom`:
+
+```sh
+npm uninstall react-router-dom
+```
+
+Replace `react-router-dom` imports with `react-router` imports:
+
+```diff
+-import { Link, useLocation } from "react-router-dom";
++import { Link, useLocation } from "react-router";
+```
+
+For DOM-specific APIs, import from `react-router/dom`:
+
+```diff
+-import { RouterProvider } from "react-router-dom";
++import { RouterProvider } from "react-router/dom";
+```
+
+### Cloudflare Vite Plugin
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+**Background**
+
+React Router v8 will remove 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
+import { reactRouter } from "@react-router/dev/vite";
+-import { cloudflareDevProxy } from "@react-router/dev/vite/cloudflare";
++import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+-    cloudflareDevProxy(),
++    cloudflare(),
+    reactRouter(),
+  ],
+});
+```
+
+### `@react-router/architect` `useRequestContextDomainName`
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+**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.
+
+👉 **Update your Code**
+
+Opt in to the v8 behavior now by passing `useRequestContextDomainName: true`:
+
+```ts
+import { createRequestHandler } from "@react-router/architect";
+import * as build from "./build/server";
+
+export const handler = createRequestHandler({
+  build,
+  useRequestContextDomainName: true,
+});
+```
+
+This option will be removed in v8 once 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.
+
+```shellscript nonumber
+# data/declarative mode
+npm install react-router@latest
+
+# framework mode
+npm install react-router@latest @react-router/{dev,node,etc.}@latest
+```
+
+Congratulations, you're now on v8!
+
+[api-development-strategy]: ../community/api-development-strategy
+[observability]: ../how-to/instrumentation
+[Response]: https://developer.mozilla.org/en-US/docs/Web/API/Response
+[vite-environment]: https://vite.dev/guide/api-environment
+[node-custom-server-template]: https://github.com/remix-run/react-router-templates/blob/7c617a435510bc3add3a5395c07bc65328b65e9e/node-custom-server/vite.config.ts
+[cloudflare-vite-plugin]: https://developers.cloudflare.com/workers/vite-plugin/

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-router",
   "type": "module",
-  "version": "8.0.0-pre.0",
+  "version": "8.0.0",
   "description": "Declarative routing for React",
   "keywords": [
     "react",
@@ -85,17 +85,17 @@
     "@types/node": "^22.19.19",
     "jest-environment-jsdom": "^30.4.1",
     "premove": "^4.0.0",
-    "react": "^19.2.6",
-    "react-dom": "^19.2.6",
-    "react-test-renderer": "^19.2.6",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-test-renderer": "^19.2.7",
     "tsdown": "^0.22.0",
     "typescript": "^6.0.3",
     "undici": "^6.19.2",
     "wireit": "0.14.12"
   },
   "peerDependencies": {
-    "react": ">=19.2.6",
-    "react-dom": ">=19.2.6"
+    "react": ">=19.2.7",
+    "react-dom": ">=19.2.7"
   },
   "peerDependenciesMeta": {
     "react-dom": {
@@ -110,7 +110,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=22.22.0"
   },
   "scripts": {
     "build": "wireit",

package/dist/development/lib/dom/ssr/errors.d.ts

@@ -1,7 +0,0 @@
-
-import { RouterState } from "../../router/router.js";
-
-//#region lib/dom/ssr/errors.d.ts
-declare function deserializeErrors(errors: RouterState["errors"]): RouterState["errors"];
-//#endregion
-export { deserializeErrors };

package/dist/development/lib/dom/ssr/errors.js

@@ -1,36 +0,0 @@
-/**
- * react-router v8.0.0-pre.0
- *
- * Copyright (c) Remix Software Inc.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE.md file in the root directory of this source tree.
- *
- * @license MIT
- */
-import { ErrorResponseImpl } from "../../router/utils.js";
-//#region lib/dom/ssr/errors.ts
-function deserializeErrors(errors) {
-	if (!errors) return null;
-	let entries = Object.entries(errors);
-	let serialized = {};
-	for (let [key, val] of entries) if (val && val.__type === "RouteErrorResponse") serialized[key] = new ErrorResponseImpl(val.status, val.statusText, val.data, val.internal === true);
-	else if (val && val.__type === "Error") {
-		if (val.__subType) {
-			let ErrorConstructor = window[val.__subType];
-			if (typeof ErrorConstructor === "function") try {
-				let error = new ErrorConstructor(val.message);
-				error.stack = val.stack;
-				serialized[key] = error;
-			} catch (e) {}
-		}
-		if (serialized[key] == null) {
-			let error = new Error(val.message);
-			error.stack = val.stack;
-			serialized[key] = error;
-		}
-	} else serialized[key] = val;
-	return serialized;
-}
-//#endregion
-export { deserializeErrors };