react-router 8.4.0 → 8.5.1

package/docs/how-to/error-reporting.md

@@ -6,9 +6,6 @@ title: Error Reporting
 
 [MODES: framework,data]
 
-<br/>
-<br/>
-
 React Router catches errors in your route modules and sends them to [error boundaries](./error-boundary) to prevent blank pages when errors occur. However, `ErrorBoundary` isn't sufficient for logging and reporting errors.
 
 ## Server Errors

package/docs/how-to/fetchers.md

@@ -6,9 +6,6 @@ title: Using Fetchers
 
 [MODES: framework, data]
 
-<br/>
-<br/>
-
 Fetchers are useful for creating complex, dynamic user interfaces that require multiple, concurrent data interactions without causing a navigation.
 
 Fetchers track their own, independent state and can be used to load data, mutate data, submit forms, and generally interact with loaders and actions.

package/docs/how-to/file-route-conventions.md

@@ -6,9 +6,6 @@ title: File Route Conventions
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 The `@react-router/fs-routes` package enables file-convention based route config.
 
 ## Setting up

package/docs/how-to/file-uploads.md

@@ -6,9 +6,6 @@ title: File Uploads
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 _Thank you to David Adams for [writing an original guide](https://programmingarehard.com/2024/09/06/remix-file-uploads-updated.html/) on which this doc is based. You can refer to it for even more examples._
 
 ## Basic File Upload

package/docs/how-to/form-validation.md

@@ -6,9 +6,6 @@ title: Form Validation
 
 [MODES: framework, data]
 
-<br/>
-<br/>
-
 This guide walks through a simple signup form implementation. You will likely want to pair these concepts with third-party validation libraries and error components, but this guide only focuses on the moving pieces for React Router.
 
 ## 1. Setting Up

package/docs/how-to/headers.md

@@ -6,9 +6,6 @@ title: HTTP Headers
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 ## Reading request headers
 
 The `request` sent to route handlers is a standard Web Fetch [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request), so you can read headers directly from the [`request.headers`](https://developer.mozilla.org/en-US/docs/Web/API/Request/headers) property:

package/docs/how-to/instrumentation.md

@@ -6,9 +6,6 @@ title: Instrumentation
 
 [MODES: framework, data]
 
-<br/>
-<br/>
-
 Instrumentation allows you to add logging, error reporting, and performance tracing to your React Router application without modifying your actual route handlers. This enables comprehensive observability solutions for production applications on both the server and client.
 
 ## Overview

package/docs/how-to/middleware.md

@@ -6,9 +6,6 @@ title: Middleware
 
 [MODES: framework, data]
 
-<br/>
-<br/>
-
 Middleware allows you to run code before and after the [`Response`][Response] generation for the matched path. This enables [common patterns][common-patterns] like authentication, logging, error handling, and data preprocessing in a reusable way.
 
 Middleware runs in a nested chain, executing from parent routes to child routes on the way "down" to your route handlers, then from child routes back to parent routes on the way "up" after a [`Response`][Response] is generated.
@@ -474,6 +471,12 @@ Which `ErrorBoundary` is rendered will differ based on whether your middleware t
 
 ### Authentication
 
+Middleware on a protected route or a common ancestor can authenticate and authorize a request before the matched loaders and actions run.
+
+Loaders run in parallel and can be requested independently, so parent loaders are not capable of "protecting" child route loaders or actions. Each protected loader and action must perform its own checks unless appropriate server middleware enforces them before the handler runs.
+
+<docs-warning>Attach authorization middleware to the protected route or layout instead of gating its checks with literal pathname-prefix comparisons such as `url.pathname.startsWith("/admin")`. Literal checks may miss potential URL encodings that React Router route matching would cover.</docs-warning>
+
 ```tsx filename=app/middleware/auth.ts
 import { redirect } from "react-router";
 import { userContext } from "~/context";
@@ -635,6 +638,7 @@ export async function loader({
 [server-client]: #server-vs-client-middleware
 [framework-action]: ../start/framework/route-module#action
 [framework-loader]: ../start/framework/route-module#loader
+[getloadcontext]: ../api/other-api/adapter#react-routerexpress
 [datastrategy]: ../api/data-routers/createBrowserRouter#optsdatastrategy
 [cms-redirect]: #cms-redirect-on-404
 [createContext]: ../api/utils/createContext

package/docs/how-to/navigation-blocking.md

@@ -6,9 +6,6 @@ title: Navigation Blocking
 
 [MODES: framework, data]
 
-<br/>
-<br/>
-
 When users are in the middle of a workflow, like filling out an important form, you may want to prevent them from navigating away from the page.
 
 This example will show:

package/docs/how-to/optimize-revalidation.md

@@ -6,9 +6,6 @@ title: Revalidation Optimization
 
 [MODES: framework, data]
 
-<br/>
-<br/>
-
 After a mutation or some navigations, React Router re-runs loaders so
 the UI stays in sync with the server. That default is the right
 starting point. When a loader is expensive, or a mutation cannot
@@ -25,10 +22,10 @@ Prefer targeting a specific action or navigation, and fall back to
 The default behavior differs between Framework and Data Modes:
 
 - **Framework Mode with SSR**
-  - Defaults to opt-out behavior - active loaders are revalidated on navigations and successful submissions ([`Link`][link], [`Form`][form], [`fetcher.submit`](fetcher-submit))
+  - Defaults to opt-out behavior - active loaders are revalidated on navigations and successful submissions ([`Link`][link], [`Form`][form], [`fetcher.submit`][use-fetcher])
   - Failed submissions returning a 4xx/5xx status do not trigger revalidations by default
 - **Framework "SPA Mode" and Data Mode**
-  - Defaults to opt-out behavior on successful submissions - active loaders are revalidated on successful submissions ([`Form`][form], [`fetcher.submit`])
+  - Defaults to opt-out behavior on successful submissions - active loaders are revalidated on successful submissions ([`Form`][form], [`fetcher.submit`][use-fetcher])
     - Failed submissions returning a 4xx/5xx status do not trigger revalidations by default
   - Defaults to opt-in behavior for GET navigations ([`Link`][link]) - active loaders are only revalidated if their dynamic params changed, or if any search params changed
     - A GET navigation to the _exact_ same URL is treated like a page refresh and all loaders are revalidated.

package/docs/how-to/pre-rendering.md

@@ -6,9 +6,6 @@ title: Pre-Rendering
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 Pre-Rendering allows you to speed up page loads for static content by rendering pages at build time instead of at runtime.
 
 ## Configuration
@@ -84,10 +81,11 @@ export default {
 
 ## Pre-Rendering with/without a Runtime Server
 
-Pre-Rendering can be used in two ways based on the `ssr` config value:
+Pre-Rendering can be used with these `ssr` config values:
 
 - Alongside a runtime SSR server with `ssr:true` (the default value)
 - Deployed to a static file server with `ssr:false`
+- Alongside a runtime API server with `ssr:"unstable_api-only"` (experimental)
 
 ### Pre-rendering with `ssr:true`
 
@@ -223,3 +221,24 @@ When pre-rendering with `ssr:false`, React Router will error at build time if yo
   - If you are using a `loader` on a pre-rendered route that has child routes, you will need to make sure the parent `loaderData` can be determined at run-time properly by either:
     - Pre-rendering all child routes so that the parent `loader` can be called at build-time for each child route path and rendered into a `.data` file, or
     - Use a `clientLoader` on the parent that can be called at run-time for non-pre-rendered child paths
+
+### Pre-rendering with API-only Mode (unstable)
+
+<docs-warning>API-only Mode is experimental and may change in minor or patch releases. It is not supported in RSC Framework Mode.</docs-warning>
+
+Use `ssr: "unstable_api-only"` with `prerender` to generate documents at build time while keeping a runtime server for loaders, actions, and route discovery:
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: "unstable_api-only",
+  prerender: ["/"],
+} satisfies Config;
+```
+
+Document generation follows the same behavior as `ssr:false`: selected paths produce HTML and `.data` files, and other paths use a SPA fallback. The fallback is `__spa-fallback.html` when `/` is prerendered, or `index.html` otherwise.
+
+Prerendered pages hydrate using their build-time data. Pages using the fallback fetch server loader data during initialization. Server loaders and actions are available on all routes, including those outside the prerender list, and normal loader revalidation remains enabled.
+
+See [API-only Mode](../start/framework/rendering#api-only-mode-unstable) for deployment routing and configuring a separate API origin.

package/docs/how-to/presets.md

@@ -6,9 +6,6 @@ title: Presets
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 The [React Router config][react-router-config] supports a `presets` option to ease integration with other tools and hosting providers.
 
 [Presets][preset-type] can only do two things:

package/docs/how-to/react-server-components.md

@@ -7,9 +7,6 @@ unstable: true
 
 [MODES: framework, data]
 
-<br/>
-<br/>
-
 <docs-warning>React Server Components support is experimental and subject to breaking changes in
 minor/patch releases. Please use with caution and pay **very** close attention
 to release notes for relevant changes.</docs-warning>

package/docs/how-to/resource-routes.md

@@ -6,9 +6,6 @@ title: Resource Routes
 
 [MODES: framework, data]
 
-<br/>
-<br/>
-
 When server rendering, routes can serve "resources" instead of rendering components, like images, PDFs, JSON payloads, webhooks, etc.
 
 ## Defining a Resource Route

package/docs/how-to/route-discovery.md

@@ -0,0 +1,147 @@
+---
+title: Route Discovery
+unstable: true
+---
+
+# Route Discovery
+
+[MODES: framework]
+
+<docs-warning>This API is unstable and may change without a major release. It supports conventional Framework Mode; RSC modes are not supported.</docs-warning>
+
+Enable the future flag in `react-router.config.ts`:
+
+```ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  future: { unstable_customRouteDiscovery: true },
+} satisfies Config;
+```
+
+Without this flag, React Router keeps its existing discovery implementation and the hook is unavailable. The flag supports conventional Framework Mode only.
+
+Enabling the flag does not require a custom implementation or a call to `unstable_useRouteDiscovery`. React Router continues to discover routes automatically and uses its built-in manifest-mismatch recovery unless you provide a custom `onManifestMismatch` handler.
+
+Keep `routeDiscovery.mode: "lazy"` (the default for SSR) and use `unstable_useRouteDiscovery` to choose when to discover destinations or load the complete route manifest.
+
+```tsx
+let { state, discoverRoutes, loadAllRoutes } =
+  unstable_useRouteDiscovery({
+    onManifestMismatch: async (event) => {
+      // Handle mismatch, potentially by loading the entire manifest
+      await loadAllRoutes();
+    },
+  });
+
+// state: "partial" | "loading" | "complete"
+
+// Eagerly discover specific paths
+let result = await discoverRoutes(paths);
+```
+
+## Imperative Route Discovery
+
+You can control route discovery through `discoverRoutes()` without having to render links/forms on the page - this allows you to eagerly discover routes that are not directly linked from the current UI. Note that discovery only loads route metadata - it does not navigate, run loaders/actions, or prefetch route modules/stylesheets. Paths are batched within the manifest request URL limit and previously discovered paths are skipped.
+
+`discoverRoutes(paths, { signal })` accepts application-root paths beginning with `/`. React Router applies the configured `basename` and ignores query strings and hashes. Relative paths and external URLs are not supported.
+
+The result is `{ type: "success" }`, `{ type: "version-mismatch" }`, or `{ type: "aborted" }`. Success means the discovery operation completed successfully; it does not guarantee that a request was sent or that each pathname matches a route. Cached paths need no request, and a concurrent full-manifest load can supersede an incremental request failure. Unrecovered request failures and unrelated handler errors reject. Imperative mismatches do not automatically trigger a reload.
+
+For example, the cart's checkout link automatically discovers the shipping route. Use the hook to discover later checkout steps when the cart mounts, even though those steps aren't linked from the cart:
+
+```tsx
+import { useEffect } from "react";
+import {
+  Link,
+  unstable_useRouteDiscovery,
+} from "react-router";
+
+function Cart() {
+  let { discoverRoutes } = unstable_useRouteDiscovery();
+
+  useEffect(() => {
+    let controller = new AbortController();
+
+    discoverRoutes(
+      ["/checkout/billing", "/checkout/review"],
+      { signal: controller.signal },
+    ).catch(console.error);
+
+    return () => controller.abort();
+  }, [discoverRoutes]);
+
+  return (
+    <>
+      {/* Render cart items and totals here. */}
+      <Link to="/checkout/shipping">
+        Proceed to checkout
+      </Link>
+    </>
+  );
+}
+```
+
+## Completing discovery
+
+`loadAllRoutes()` loads the running client's versioned manifest asset to complete its route tree, even if that client is stale. This merges all missing routes into the running router and thus prevents further incremental discovery. The exposed `version` remains the version of the running client. With `routeDiscovery.mode: "initial"`, SPA Mode, or development's full manifest, the state is already `complete` and the operations are successful no-ops.
+
+The shared `state` moves from `partial` to `loading` to `complete`. Concurrent calls share a load, and calls after completion resolve immediately. Failures reject and return the state to `partial`; applications can catch the error and choose whether to reload.
+
+Retain the client's versioned manifest **and its referenced assets** for as long as that client is supported. Server routing and loader/action contracts must also remain compatible. Loading build A's manifest does not make an incompatible build B backend safe for build A's client.
+
+## Handling manifest mismatches
+
+You can provide custom handling for manifest version mismatches to avoid hard reloads, giving you a chance to complete the route tree, or cancel the navigation and provide a prompt for the user to reload (see below). A mismatch indicates different versions, not which version is newer.
+
+```tsx
+unstable_useRouteDiscovery({
+  onManifestMismatch: async (event) => {
+    await event.loadAllRoutes();
+  },
+});
+```
+
+After mismatch handlers settle, surviving operations continue only if the tree is complete. Otherwise navigations and fetchers are canceled and their pending state settles. Canceling a navigation also cancels any pending revalidation - both return to idle and the current page and data remain in place without another loader pass. Similarly, interrupted fetcher loads settle with their existing data. If an action already changed server data, the displayed data may remain stale until a later navigation or explicit revalidation.
+
+Router-managed Back/Forward cancellations restore the prior history position. Additional browser Back/Forward presses during restoration can leave the URL and rendered route out of sync or navigate to another entry; preserving the current screen is not guaranteed in that case.
+
+Full-manifest load failures remain catchable and do not render route error boundaries, whether the handler calls `event.loadAllRoutes()` or the function returned by the hook. Uncaught full-load failures are reported through `<HydratedRouter onError>` or `console.error`, and the incomplete operation is canceled. Unrelated handler errors follow normal discovery error handling.
+
+## Temporary overrides
+
+Custom mismatch handlers override built-in recovery. Calling the hook without a handler does not override anything. Removing the last custom mismatch handler restores automatic recovery.
+
+Call `event.defaultBehavior()` to explicitly run built-in recovery: eager mismatches warn, navigation mismatches reload the destination, fetcher mismatches reload the current document, and imperative mismatches return without reloading. Repeated calls for one shared mismatch event reuse the same promise. It does not invoke other custom handlers or stop their propagation.
+
+```tsx
+unstable_useRouteDiscovery({
+  async onManifestMismatch(event) {
+    if (hasUnsavedChanges) {
+      event.stopPropagation();
+      setShowReloadDialog(true);
+      return;
+    }
+    await event.defaultBehavior();
+  },
+});
+```
+
+Custom handlers run in reverse registration order, with each awaited before the next. `stopPropagation()` prevents earlier handlers from running; it does not complete discovery or allow an operation to continue against an incomplete tree.
+
+```tsx
+unstable_useRouteDiscovery({
+  onManifestMismatch(event) {
+    if (hasUnsavedChanges) {
+      event.stopPropagation();
+      setShowReloadDialog(true);
+    }
+  },
+});
+```
+
+An editor mounted after a root recovery handler can use this to preserve a draft. Unmounting removes its registration and reveals earlier handlers. Callback updates preserve registration priority. This is registration order, not a guarantee that the deepest component runs first.
+
+Eager discovery waits for the initialized route tree to commit so a root handler can intercept the first request. It does not wait for every suspended descendant or guarantee an idle main thread. Discovery needed before handlers can mount retains normal lazy behavior.
+
+Without mismatch handlers, existing automatic recovery for eager/navigation/fetcher discovery remains unchanged. Deployment polling and staleness policy remain application-owned.

package/docs/how-to/route-module-type-safety.md

@@ -6,9 +6,6 @@ title: Route Module Type Safety
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 React Router generates route-specific types to power type inference for URL params, loader data, and more.
 This guide will help you set it up if you didn't start with a template.
 

package/docs/how-to/security.md

@@ -6,9 +6,6 @@ title: Security
 
 [MODES: framework, data]
 
-<br/>
-<br/>
-
 This is by no means a comprehensive guide, but React Router provides features to help address a few aspects under the _very large_ umbrella that is _Security_.
 
 ## `Content-Security-Policy`

package/docs/how-to/server-bundles.md

@@ -6,9 +6,6 @@ title: Server Bundles
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 <docs-warning>This is an advanced feature designed for hosting provider integrations. When compiling your app into multiple server bundles, there will need to be a custom routing layer in front of your app directing requests to the correct bundle.</docs-warning>
 
 React Router typically builds your server code into a single bundle that exports a request handler function. However, there are scenarios where you might want to split your route tree into multiple server bundles, each exposing a request handler function for a subset of routes. To provide this flexibility, [`react-router.config.ts`][react-router-config] supports a `serverBundles` option, which is a function for assigning routes to different server bundles.

package/docs/how-to/spa.md

@@ -6,9 +6,6 @@ title: Single Page App (SPA)
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 <docs-info>This guide focuses on how to build Single Page Apps with React Router Framework mode. If you're using React Router in declarative or data mode, you can design your own SPA architecture.</docs-info>
 
 When using React Router as a framework, you can enable "SPA Mode" by setting `ssr:false` in your `react-router.config.ts` file. This will disable runtime server rendering and generate an `index.html` at build time that you can serve and hydrate as a SPA.
@@ -22,6 +19,8 @@ Typical Single Page apps send a mostly blank `index.html` template with little m
 
 <docs-info>SPA Mode is a special form of "Pre-Rendering" that allows you to serve all paths in your application from the same HTML file. Please refer to the [Pre-Rendering](./pre-rendering) guide if you want to do more extensive pre-rendering.</docs-info>
 
+<docs-info>If you want a SPA frontend backed by React Router server loaders and actions, see experimental [API-only Mode](../start/framework/rendering#api-only-mode-unstable).</docs-info>
+
 ## 1. Disable Runtime Server Rendering
 
 Server rendering is enabled by default. Set the `ssr` flag to `false` in `react-router.config.ts` to disable it.

package/docs/how-to/status.md

@@ -6,9 +6,6 @@ title: Status Codes
 
 [MODES: framework ,data]
 
-<br/>
-<br/>
-
 Set status codes from loaders and actions with `data`.
 
 ```tsx filename=app/project.tsx lines=[3,12-15,20,23]

package/docs/how-to/suspense.md

@@ -6,9 +6,6 @@ title: Streaming with Suspense
 
 [MODES: framework, data]
 
-<br/>
-<br/>
-
 Streaming with React Suspense allows apps to speed up initial renders by deferring non-critical data and unblocking UI rendering.
 
 React Router supports React Suspense by returning promises from loaders and actions.
@@ -66,9 +63,28 @@ export default function MyComponent({
 }
 ```
 
-## With React 19
+## Opt into React's `use()` API
+
+<docs-warning>The `unstable_promise` prop is experimental and may change in minor or patch releases.</docs-warning>
+
+Use `<Await unstable_promise>` instead of `<Await resolve>` to opt into `React.use` under the hood while keeping the Await API:
+
+```tsx
+<React.Suspense fallback={<div>Loading...</div>}>
+  <Await
+    unstable_promise={nonCriticalData}
+    errorElement={<LoadingError />}
+  >
+    {(value) => <h3>Non critical value: {value}</h3>}
+  </Await>
+</React.Suspense>
+```
+
+This should largely behave the same as `<Await resolve>` while avoiding the legacy React Router promise tracking. Both support render-prop children, `useAsyncValue`, and `useAsyncError`. One notable difference with `unstable_promise` is that `errorElement` only handles promise rejections. Errors thrown while rendering children bubble to the nearest React error boundary.
+
+## Use React directly
 
-If you're using React 19, you can use `React.use` instead of `Await`, but you'll need to create a new component and pass the promise down to trigger the suspense fallback.
+You can also read the promise directly with `React.use`. Pass it to a child component rendered inside `<React.Suspense>` so the boundary can display its fallback while the promise is pending.
 
 ```tsx
 <React.Suspense fallback={<div>Loading...</div>}>
@@ -94,7 +110,7 @@ export const streamTimeout = 10_000;
 
 ## Handling early rejections (Node)
 
-React Router waits for all loaders to settle (via `Promise.all`) before it begins streaming the response. Once streaming has started, React Router catches subsequent rejections of your streamed promises and surfaces them to your `<Await>` (or React 19 `React.use`) error UI.
+React Router waits for all loaders to settle (via `Promise.all`) before it begins streaming the response. Once streaming has started, React Router catches subsequent rejections of your streamed promises and surfaces them to your `<Await>` (or `React.use`) error UI.
 
 However, if a streamed promise rejects _before_ all of the route's loaders have settled, React Router has not yet been able to attach a handler to it. In Node, an unhandled promise rejection will crash the process unless you have a top-level handler registered.
 

package/docs/how-to/using-handle.md

@@ -6,9 +6,6 @@ title: Using handle
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 You can build dynamic UI elements like breadcrumbs based on your route hierarchy using the [`useMatches`][use-matches] hook and [`handle`][handle] route exports.
 
 ## Understanding the Basics