npm - react-router - Versions diffs - 7.15.1 → 7.17.0 - Mend

react-router 7.15.1 → 7.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (157) hide show

package/CHANGELOG.md +27 -2
package/dist/development/{browser-3AnU12UI.d.mts → browser-CGcs-0pD.d.mts} +2 -2
package/dist/development/{browser-BOdXz9dK.d.ts → browser-D3uq9sI1.d.ts} +2 -2
package/dist/development/{chunk-4N6VE7H7.mjs → chunk-6CSD65Y2.mjs} +12 -11
package/dist/development/{chunk-RJYABSBD.mjs → chunk-ASILSGTR.mjs} +6 -6
package/dist/development/{chunk-D6LUOGOQ.js → chunk-KFNXW4AL.js} +10 -10
package/dist/{production/chunk-Y6IFXO7V.js → development/chunk-PBLBZ3QU.js} +7 -7
package/dist/development/{chunk-66UKHEGQ.js → chunk-PULC7NLK.js} +100 -99
package/dist/{production/context-ByvtofY2.d.mts → development/context-CmHpk1Ws.d.mts} +3 -3
package/dist/development/{data-BqZ2x964.d.ts → data-D4xhSy90.d.ts} +1 -1
package/dist/{production/data-BVUf681J.d.mts → development/data-U8FS-wNn.d.mts} +1 -1
package/dist/development/dom-export.d.mts +4 -4
package/dist/development/dom-export.d.ts +4 -4
package/dist/development/dom-export.js +30 -30
package/dist/development/dom-export.mjs +5 -5
package/dist/{production/index-react-server-client-BS5F89FR.d.ts → development/index-react-server-client-CwU9bE5R.d.ts} +4 -4
package/dist/{production/index-react-server-client-DY04-103.d.mts → development/index-react-server-client-DPrDrCew.d.mts} +3 -3
package/dist/development/index-react-server-client.d.mts +3 -3
package/dist/development/index-react-server-client.d.ts +3 -3
package/dist/development/index-react-server-client.js +4 -4
package/dist/development/index-react-server-client.mjs +2 -2
package/dist/development/index-react-server.d.mts +1 -1
package/dist/development/index-react-server.d.ts +1 -1
package/dist/development/index-react-server.js +1 -1
package/dist/development/index-react-server.mjs +1 -1
package/dist/development/index.d.mts +18 -12
package/dist/development/index.d.ts +18 -12
package/dist/development/index.js +89 -89
package/dist/development/index.mjs +3 -3
package/dist/{production/instrumentation-cRWWLfsU.d.ts → development/instrumentation-1q4YhLGP.d.ts} +2 -2
package/dist/development/lib/types/internal.d.mts +2 -2
package/dist/development/lib/types/internal.d.ts +2 -2
package/dist/development/lib/types/internal.js +1 -1
package/dist/development/lib/types/internal.mjs +1 -1
package/dist/development/{register-Bsscfj79.d.ts → register-CNAx3TXj.d.ts} +1 -1
package/dist/development/{register-Df8okEea.d.mts → register-CqK96Zfk.d.mts} +1 -1
package/dist/production/{browser-3AnU12UI.d.mts → browser-CGcs-0pD.d.mts} +2 -2
package/dist/production/{browser-BOdXz9dK.d.ts → browser-D3uq9sI1.d.ts} +2 -2
package/dist/production/{chunk-6S4627ZB.mjs → chunk-5TQZEVD5.mjs} +6 -6
package/dist/{development/chunk-4YRVXM2U.js → production/chunk-CTIXC7EV.js} +7 -7
package/dist/production/{chunk-PNZCCTKT.js → chunk-EN242BO4.js} +100 -99
package/dist/production/{chunk-JAKZPQZC.mjs → chunk-OSYEOCBT.mjs} +12 -11
package/dist/production/{chunk-HUBUW7R3.js → chunk-RTRY3JFT.js} +10 -10
package/dist/{development/context-ByvtofY2.d.mts → production/context-CmHpk1Ws.d.mts} +3 -3
package/dist/production/{data-BqZ2x964.d.ts → data-D4xhSy90.d.ts} +1 -1
package/dist/{development/data-BVUf681J.d.mts → production/data-U8FS-wNn.d.mts} +1 -1
package/dist/production/dom-export.d.mts +4 -4
package/dist/production/dom-export.d.ts +4 -4
package/dist/production/dom-export.js +30 -30
package/dist/production/dom-export.mjs +5 -5
package/dist/{development/index-react-server-client-BS5F89FR.d.ts → production/index-react-server-client-CwU9bE5R.d.ts} +4 -4
package/dist/{development/index-react-server-client-DY04-103.d.mts → production/index-react-server-client-DPrDrCew.d.mts} +3 -3
package/dist/production/index-react-server-client.d.mts +3 -3
package/dist/production/index-react-server-client.d.ts +3 -3
package/dist/production/index-react-server-client.js +4 -4
package/dist/production/index-react-server-client.mjs +2 -2
package/dist/production/index-react-server.d.mts +1 -1
package/dist/production/index-react-server.d.ts +1 -1
package/dist/production/index-react-server.js +1 -1
package/dist/production/index-react-server.mjs +1 -1
package/dist/production/index.d.mts +18 -12
package/dist/production/index.d.ts +18 -12
package/dist/production/index.js +89 -89
package/dist/production/index.mjs +3 -3
package/dist/{development/instrumentation-cRWWLfsU.d.ts → production/instrumentation-1q4YhLGP.d.ts} +2 -2
package/dist/production/lib/types/internal.d.mts +2 -2
package/dist/production/lib/types/internal.d.ts +2 -2
package/dist/production/lib/types/internal.js +1 -1
package/dist/production/lib/types/internal.mjs +1 -1
package/dist/production/{register-Bsscfj79.d.ts → register-CNAx3TXj.d.ts} +1 -1
package/dist/production/{register-Df8okEea.d.mts → register-CqK96Zfk.d.mts} +1 -1
package/docs/explanation/backend-for-frontend.md +50 -0
package/docs/explanation/code-splitting.md +61 -0
package/docs/explanation/concurrency.md +135 -0
package/docs/explanation/form-vs-fetcher.md +292 -0
package/docs/explanation/hot-module-replacement.md +137 -0
package/docs/explanation/hydration.md +14 -0
package/docs/explanation/index-query-param.md +86 -0
package/docs/explanation/index.md +4 -0
package/docs/explanation/lazy-route-discovery.md +78 -0
package/docs/explanation/location.md +6 -0
package/docs/explanation/progressive-enhancement.md +150 -0
package/docs/explanation/race-conditions.md +88 -0
package/docs/explanation/react-transitions.md +160 -0
package/docs/explanation/route-matching.md +7 -0
package/docs/explanation/server-client-execution.md +4 -0
package/docs/explanation/sessions-and-cookies.md +465 -0
package/docs/explanation/special-files.md +16 -0
package/docs/explanation/state-management.md +524 -0
package/docs/explanation/styling.md +87 -0
package/docs/explanation/type-safety.md +82 -0
package/docs/how-to/accessibility.md +44 -0
package/docs/how-to/client-data.md +199 -0
package/docs/how-to/data-strategy.md +317 -0
package/docs/how-to/error-boundary.md +231 -0
package/docs/how-to/error-reporting.md +142 -0
package/docs/how-to/fetchers.md +307 -0
package/docs/how-to/file-route-conventions.md +410 -0
package/docs/how-to/file-uploads.md +217 -0
package/docs/how-to/form-validation.md +120 -0
package/docs/how-to/headers.md +164 -0
package/docs/how-to/index.md +4 -0
package/docs/how-to/instrumentation.md +556 -0
package/docs/how-to/meta.md +40 -0
package/docs/how-to/middleware.md +763 -0
package/docs/how-to/navigation-blocking.md +233 -0
package/docs/how-to/optimize-revalidation.md +12 -0
package/docs/how-to/pre-rendering.md +225 -0
package/docs/how-to/presets.md +103 -0
package/docs/how-to/react-server-components.md +899 -0
package/docs/how-to/resource-routes.md +126 -0
package/docs/how-to/route-module-type-safety.md +100 -0
package/docs/how-to/search-params.md +4 -0
package/docs/how-to/security.md +30 -0
package/docs/how-to/server-bundles.md +66 -0
package/docs/how-to/spa.md +120 -0
package/docs/how-to/status.md +63 -0
package/docs/how-to/suspense.md +132 -0
package/docs/how-to/using-handle.md +117 -0
package/docs/how-to/view-transitions.md +237 -0
package/docs/how-to/webhook.md +50 -0
package/docs/index.md +39 -0
package/docs/start/data/actions.md +138 -0
package/docs/start/data/custom.md +198 -0
package/docs/start/data/data-loading.md +44 -0
package/docs/start/data/index.md +4 -0
package/docs/start/data/installation.md +52 -0
package/docs/start/data/navigating.md +12 -0
package/docs/start/data/pending-ui.md +12 -0
package/docs/start/data/route-object.md +268 -0
package/docs/start/data/routing.md +281 -0
package/docs/start/data/testing.md +8 -0
package/docs/start/declarative/index.md +4 -0
package/docs/start/declarative/installation.md +43 -0
package/docs/start/declarative/navigating.md +133 -0
package/docs/start/declarative/routing.md +237 -0
package/docs/start/declarative/url-values.md +65 -0
package/docs/start/framework/actions.md +174 -0
package/docs/start/framework/data-loading.md +201 -0
package/docs/start/framework/deploying.md +96 -0
package/docs/start/framework/index.md +4 -0
package/docs/start/framework/installation.md +41 -0
package/docs/start/framework/navigating.md +182 -0
package/docs/start/framework/pending-ui.md +142 -0
package/docs/start/framework/rendering.md +59 -0
package/docs/start/framework/route-module.md +527 -0
package/docs/start/framework/routing.md +362 -0
package/docs/start/framework/testing.md +133 -0
package/docs/start/index.md +4 -0
package/docs/start/modes.md +201 -0
package/docs/upgrading/component-routes.md +363 -0
package/docs/upgrading/future.md +280 -0
package/docs/upgrading/index.md +4 -0
package/docs/upgrading/remix.md +403 -0
package/docs/upgrading/router-provider.md +442 -0
package/docs/upgrading/v6.md +382 -0
package/package.json +2 -1

package/docs/upgrading/component-routes.md ADDED Viewed

@@ -0,0 +1,363 @@
+---
+title: Framework Adoption from Component Routes
+order: 4
+---
+# Framework Adoption from Component Routes
+If you are using `<RouterProvider>` please see [Framework Adoption from RouterProvider][upgrade-router-provider] instead.
+If you are using `<Routes>` this is the right place.
+The React Router Vite plugin adds framework features to React Router. This guide will help you adopt the plugin in your app. If you run into any issues, please reach out for help on [Twitter](https://x.com/remix_run) or [Discord](https://rmx.as/discord).
+## Features
+The Vite plugin adds:
+- Route loaders, actions, and automatic data revalidation
+- Type-safe Routes Modules
+- Automatic route code-splitting
+- Automatic scroll restoration across navigations
+- Optional Static pre-rendering
+- Optional Server rendering
+The initial setup requires the most work. However, once complete, you can adopt new features incrementally, one route at a time.
+## Prerequisites
+To use the Vite plugin, your project requires:
+- Node.js 20+ (if using Node as your runtime)
+- Vite 5+
+## 1. Install the Vite plugin
+**👉 Install the React Router Vite plugin**
+```shellscript nonumber
+npm install -D @react-router/dev
+```
+**👉 Install a runtime adapter**
+We will assume you are using Node as your runtime.
+```shellscript nonumber
+npm install @react-router/node
+```
+**👉 Swap out the React plugin for React Router.**
+```diff filename=vite.config.ts
+-import react from '@vitejs/plugin-react'
++import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+export default defineConfig({
+  plugins: [
+-    react()
++    reactRouter()
+  ],
+});
+```
+## 2. Add the React Router config
+**👉 Create a `react-router.config.ts` file**
+Add the following to the root of your project. In this config you can tell React Router about your project, like where to find the app directory and to not use SSR (server-side rendering) for now.
+```shellscript nonumber
+touch react-router.config.ts
+```
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+export default {
+  appDirectory: "src",
+  ssr: false,
+} satisfies Config;
+```
+## 3. Add the Root entry point
+In a typical Vite app, the `index.html` file is the entry point for bundling. The React Router Vite plugin moves the entry point to a `root.tsx` file so you can use React to render the shell of your app instead of static HTML, and eventually upgrade to Server Rendering if you want.
+**👉 Move your existing `index.html` to `root.tsx`**
+For example, if your current `index.html` looks like this:
+```html filename=index.html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0"
+    />
+    <title>My App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
+```
+You would move that markup into `src/root.tsx` and delete `index.html`:
+```shellscript nonumber
+touch src/root.tsx
+```
+```tsx filename=src/root.tsx
+import {
+  Links,
+  Meta,
+  Outlet,
+  Scripts,
+  ScrollRestoration,
+} from "react-router";
+export function Layout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="UTF-8" />
+        <meta
+          name="viewport"
+          content="width=device-width, initial-scale=1.0"
+        />
+        <title>My App</title>
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        {children}
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+export default function Root() {
+  return <Outlet />;
+}
+```
+## 4. Add client entry module
+In the typical Vite app the `index.html` file points to `src/main.tsx` as the client entry point. React Router uses a file named `src/entry.client.tsx` instead.
+**👉 Make `src/entry.client.tsx` your entry point**
+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 "./index.css";
+import App from "./App";
+ReactDOM.createRoot(
+  document.getElementById("root")!,
+).render(
+  <React.StrictMode>
+    <BrowserRouter>
+      <App />
+    </BrowserRouter>
+  </React.StrictMode>,
+);
+```
+You would rename it to `entry.client.tsx` and change it to this:
+```tsx filename=src/entry.client.tsx
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { HydratedRouter } from "react-router/dom";
+import "./index.css";
+ReactDOM.hydrateRoot(
+  document,
+  <React.StrictMode>
+    <HydratedRouter />
+  </React.StrictMode>,
+);
+```
+- Use `hydrateRoot` instead of `createRoot`
+- Render a `<HydratedRouter>` instead of your `<App/>` component
+- Note: we stopped rendering the `<App/>` component. We'll bring it back in a later step, but first we want to get the app to boot with the new entry point.
+## 5. Shuffle stuff around
+Between `root.tsx` and `entry.client.tsx`, you may want to shuffle some stuff around between them.
+In general:
+- `root.tsx` contains any rendering things like context providers, layouts, styles, etc.
+- `entry.client.tsx` should be as minimal as possible
+- Remember to _not_ try to render your existing `<App/>` component yet, we'll do that in a later step
+Note that your `root.tsx` file will be statically generated and served as the entry point of your app, so just that module will need to be compatible with server rendering. This is where most of your trouble will come.
+## 6. Set up your routes
+The React Router Vite plugin uses a `routes.ts` file to configure your routes. For now we'll add a simple catchall route to get things going.
+**👉 Set up a `catchall.tsx` route**
+```shellscript nonumber
+touch src/routes.ts src/catchall.tsx
+```
+```ts filename=src/routes.ts
+import {
+  type RouteConfig,
+  route,
+} from "@react-router/dev/routes";
+export default [
+  // * matches all URLs, the ? makes it optional so it will match / as well
+  route("*?", "catchall.tsx"),
+] satisfies RouteConfig;
+```
+**👉 Render a placeholder route**
+Eventually we'll replace this with our original `App` component, but for now we'll just render something simple to make sure we can boot the app.
+```tsx filename=src/catchall.tsx
+export default function Component() {
+  return <div>Hello, world!</div>;
+}
+```
+[View our guide on configuring routes][configuring-routes] to learn more about the `routes.ts` file.
+## 7. Boot the app
+At this point you should be able to boot the app and see the root layout.
+**👉 Add `dev` script and run the app**
+```json filename=package.json
+"scripts": {
+  "dev": "react-router dev"
+}
+```
+Now make sure you can boot your app at this point before moving on:
+```shellscript
+npm run dev
+```
+You will probably want to add `.react-router/` to your `.gitignore` file to avoid tracking unnecessary files in your repository.
+```txt
+.react-router/
+```
+You can check out [Type Safety][type-safety] to learn how to fully set up and use autogenerated type safety for params, loader data, and more.
+## 8. Render your app
+To get back to rendering your app, we'll update the "catchall" route we set up earlier that matches all URLs so that your existing `<Routes>` get a chance to render.
+**👉 Update the catchall route to render your app**
+```tsx filename=src/catchall.tsx
+import App from "./App";
+export default function Component() {
+  return <App />;
+}
+```
+Your app should be back on the screen and working as usual!
+## 9. Migrate a route to a Route Module
+You can now incrementally migrate your routes to route modules.
+Given an existing route like this:
+```tsx filename=src/App.tsx
+// ...
+import About from "./containers/About";
+export default function App() {
+  return (
+    <Routes>
+      <Route path="/about" element={<About />} />
+    </Routes>
+  );
+}
+```
+**👉 Add the route definition to `routes.ts`**
+```tsx filename=src/routes.ts
+import {
+  type RouteConfig,
+  route,
+} from "@react-router/dev/routes";
+export default [
+  route("/about", "./pages/about.tsx"),
+  route("*?", "catchall.tsx"),
+] satisfies RouteConfig;
+```
+**👉 Add the route module**
+Edit the route module to use the [Route Module API][route-modules]:
+```tsx filename=src/pages/about.tsx
+export async function clientLoader() {
+  // you can now fetch data here
+  return {
+    title: "About page",
+  };
+}
+export default function Component({ loaderData }) {
+  return <h1>{loaderData.title}</h1>;
+}
+```
+See [Type Safety][type-safety] to set up autogenerated type safety for params, loader data, and more.
+The first few routes you migrate are the hardest because you often have to access various abstractions a bit differently than before (like in a loader instead of from a hook or context). But once the trickiest bits get dealt with, you get into an incremental groove.
+## Enable SSR and/or Pre-rendering
+If you want to enable server rendering and static pre-rendering, you can do so with the `ssr` and `prerender` options in the bundler plugin. For SSR you'll need to also deploy the server build to a server.
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+export default {
+  ssr: true,
+  async prerender() {
+    return ["/", "/about", "/contact"];
+  },
+} satisfies Config;
+```
+[upgrade-router-provider]: ./router-provider
+[configuring-routes]: ../start/framework/routing
+[route-modules]: ../start/framework/route-module
+[type-safety]: ../how-to/route-module-type-safety

package/docs/upgrading/future.md ADDED Viewed

@@ -0,0 +1,280 @@
+---
+title: Future Flags
+order: 1
+---
+# Future Flags and Deprecations
+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 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
+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 v7
+```sh
+npm install react-router@7 @react-router/{dev,node,etc.}@7
+```
+## `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/dom";
+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.
+## 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!
+_No current unstable flags to document_
+[api-development-strategy]: ../community/api-development-strategy
+[unstable]: ../community/api-development-strategy#unstable-flags
+[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

package/docs/upgrading/index.md ADDED Viewed

@@ -0,0 +1,4 @@
+---
+title: Upgrading
+order: 2
+---