react-router 8.3.1 → 8.5.0

package/dist/production/lib/server-runtime/sessions/memoryStorage.js

@@ -1,5 +1,5 @@
 /**
- * react-router v8.3.1
+ * react-router v8.5.0
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/production/lib/server-runtime/sessions.js

@@ -1,5 +1,5 @@
 /**
- * react-router v8.3.1
+ * react-router v8.5.0
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/production/lib/server-runtime/single-fetch.js

@@ -1,5 +1,5 @@
 /**
- * react-router v8.3.1
+ * react-router v8.5.0
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/production/lib/server-runtime/urls.js

@@ -1,5 +1,5 @@
 /**
- * react-router v8.3.1
+ * react-router v8.5.0
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/production/lib/server-runtime/warnings.js

@@ -1,5 +1,5 @@
 /**
- * react-router v8.3.1
+ * react-router v8.5.0
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/production/lib/types/internal.js

@@ -1,5 +1,5 @@
 /**
- * react-router v8.3.1
+ * react-router v8.5.0
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/production/lib/types/route-data.d.ts

@@ -1,10 +1,10 @@
 
 import { DataWithResponseInit, RouterContextProvider } from "../router/utils.js";
+import { ClientActionFunctionArgs, ClientLoaderFunctionArgs } from "../dom/ssr/routeModules.js";
+import { Serializable } from "../server-runtime/single-fetch.js";
 import { Equal, Func, IsAny } from "./utils.js";
 import { RouteModule } from "./route-module.js";
 import { unstable_SerializesTo } from "./serializes-to.js";
-import { Serializable } from "../server-runtime/single-fetch.js";
-import { ClientActionFunctionArgs, ClientLoaderFunctionArgs } from "../dom/ssr/routeModules.js";
 
 //#region lib/types/route-data.d.ts
 type Serialize<T> = T extends unstable_SerializesTo<infer To> ? To : T extends Serializable ? T : T extends ((...args: any[]) => unknown) ? undefined : T extends Promise<infer U> ? Promise<Serialize<U>> : T extends Map<infer K, infer V> ? Map<Serialize<K>, Serialize<V>> : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<Serialize<K>, Serialize<V>> : T extends Set<infer U> ? Set<Serialize<U>> : T extends ReadonlySet<infer U> ? ReadonlySet<Serialize<U>> : T extends [] ? [] : T extends readonly [infer F, ...infer R] ? [Serialize<F>, ...Serialize<R>] : T extends Array<infer U> ? Array<Serialize<U>> : T extends readonly unknown[] ? readonly Serialize<T[number]>[] : T extends Record<any, any> ? { [K in keyof T]: Serialize<T[K]> } : undefined;

package/dist/production/lib/types/route-module-annotations.d.ts

@@ -2,10 +2,10 @@
 import { Location } from "../router/history.js";
 import { DataStrategyResult, MiddlewareNextFunction } from "../router/utils.js";
 import { LinkDescriptor } from "../router/links.js";
+import { MetaDescriptor } from "../dom/ssr/routeModules.js";
 import { Func, Pretty } from "./utils.js";
 import { RouteModule } from "./route-module.js";
 import { ClientDataFunctionArgs, GetLoaderData, ServerDataFrom, ServerDataFunctionArgs } from "./route-data.js";
-import { MetaDescriptor } from "../dom/ssr/routeModules.js";
 
 //#region lib/types/route-module-annotations.d.ts
 type MaybePromise<T> = T | Promise<T>;

package/dist/production/route-pattern.d.ts

@@ -0,0 +1,3 @@
+
+import { unstable_preloadRoutePattern } from "./lib/router/matcher-route-pattern.preload.js";
+export { unstable_preloadRoutePattern };

package/dist/production/route-pattern.js

@@ -0,0 +1,12 @@
+/**
+ * react-router v8.5.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 { unstable_preloadRoutePattern } from "./lib/router/matcher-route-pattern.preload.js";
+export { unstable_preloadRoutePattern };

package/dist/production/vendor/turbo-stream-v2/flatten.js

@@ -1,5 +1,5 @@
 /**
- * react-router v8.3.1
+ * react-router v8.5.0
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/production/vendor/turbo-stream-v2/turbo-stream.js

@@ -1,5 +1,5 @@
 /**
- * react-router v8.3.1
+ * react-router v8.5.0
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/production/vendor/turbo-stream-v2/unflatten.js

@@ -1,5 +1,5 @@
 /**
- * react-router v8.3.1
+ * react-router v8.5.0
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/production/vendor/turbo-stream-v2/utils.js

@@ -1,5 +1,5 @@
 /**
- * react-router v8.3.1
+ * react-router v8.5.0
  *
  * Copyright (c) Remix Software Inc.
  *

package/docs/explanation/lazy-route-discovery.md

@@ -76,3 +76,7 @@ When using lazy route discovery, ensure your deployment setup handles manifest r
 - **Route Handling** - Ensure `/__manifest` requests reach your React Router handler
 - **CDN Caching** - If using CDN/edge caching, include `version` and `paths` query parameters in your cache key for the manifest endpoint
 - **Multiple Applications** - Use a custom `manifestPath` if running multiple React Router applications on the same domain
+
+## Application-Controlled Discovery
+
+Use the experimental `unstable_useRouteDiscovery` hook to discover selected destinations, complete the route tree after startup, or control manifest-mismatch recovery. See [Application-Controlled Route Discovery](../how-to/route-discovery).

package/docs/explanation/sessions-and-cookies.md

@@ -59,28 +59,130 @@ The input/output to a session storage object are HTTP cookies. `getSession()` re
 
 You'll use methods to get access to sessions in your `loader` and `action` functions.
 
-After retrieving a session with `getSession`, the returned session object has a handful of methods and properties:
+### Session API
+
+After retrieving a session with `getSession()`, the returned session object has a handful of methods and properties:
 
 ```tsx
 export async function action({
   request,
-}: ActionFunctionArgs) {
+}: Route.ActionArgs) {
   const session = await getSession(
     request.headers.get("Cookie"),
   );
+
   session.get("foo");
   session.has("bar");
   // etc.
+
+  return redirect("/", {
+    headers: {
+      "Set-Cookie": await commitSession(session),
+    },
+  });
 }
 ```
 
-See the [Session API][session-api] for all methods available on the session object.
+<docs-warning>Every time you modify session data, you must `commitSession()` or your changes will be lost. When using cookie session storage, you must also send the `Set-Cookie` header it returns in your response.</docs-warning>
+
+See the [Session API][session-api] for all methods and properties available on the session object.
+
+#### `session.has(key)`
+
+Returns `true` if the session has a value (or an unread flash value) for the given `key`. This does not consume flash values.
+
+```ts
+session.has("userId");
+```
+
+#### `session.set(key, value)`
+
+Sets a session value for use in subsequent requests:
+
+```ts
+session.set("userId", "1234");
+```
+
+#### `session.flash(key, value)`
+
+Sets a session value that is only valid until the next `session.get()` for that key. After that, it's gone. Most useful for "flash messages" and server-side form validation messages:
+
+```ts
+session.flash(
+  "globalMessage",
+  "Project successfully archived",
+);
+```
+
+A flash value is typically set in an `action` before a redirect, then read in the `loader` of the page being redirected to:
+
+```tsx filename=app/routes/projects.tsx
+export async function action({
+  request,
+}: Route.ActionArgs) {
+  const session = await getSession(
+    request.headers.get("Cookie"),
+  );
+  // ...archive the project
+  session.flash(
+    "globalMessage",
+    "Project successfully archived",
+  );
+  return redirect("/projects", {
+    headers: {
+      "Set-Cookie": await commitSession(session),
+    },
+  });
+}
+
+export async function loader({
+  request,
+}: Route.LoaderArgs) {
+  const session = await getSession(
+    request.headers.get("Cookie"),
+  );
+  // Reading a flash value removes it from the session
+  const message = session.get("globalMessage");
+
+  return data(
+    { message },
+    {
+      headers: {
+        // Commit the session so the flash value is removed
+        "Set-Cookie": await commitSession(session),
+      },
+    },
+  );
+}
+```
+
+Flash values are read with `session.get()` using the same key they were set with. Reading a flash value removes it from the session, so you must still `commitSession()` after reading it; otherwise the flash value will be read again on the next request.
+
+Avoid using the same key for both `session.set()` and `session.flash()`. `session.get()` returns the regular value first, so the flash value would never be read or removed.
+
+You can type flash values separately from regular session values with the second generic on your session storage, like the `SessionFlashData` type in [Using Sessions](#using-sessions).
+
+#### `session.get(key)`
+
+Accesses a session value from a previous request:
+
+```ts
+session.get("name");
+```
+
+#### `session.unset(key)`
+
+Removes a value from the session. This does not remove pending flash values; those are only removed when read with `session.get()`.
+
+```ts
+session.unset("name");
+```
 
 ### Login form example
 
 A login form might look something like this:
 
-```tsx filename=app/routes/login.tsx lines=[4-7,12-14,16,22,25,33-35,46,51,56,61]
+```tsx filename=app/routes/login.tsx lines=[4-7,12-14,16,22-23,26,35-37,48-49,54,59,64]
 import { data, redirect } from "react-router";
 import type { Route } from "./+types/login";
 
@@ -102,6 +204,7 @@ export async function loader({
   }
 
   return data(
+    // Read and unset the flash message set by the route action.
     { error: session.get("error") },
     {
       headers: {
@@ -127,6 +230,7 @@ export async function action({
   );
 
   if (userId == null) {
+    // Set a single-use flash message to be read by the route loader.
     session.flash("error", "Invalid username/password");
 
     // Redirect back to the login page with errors.

package/docs/how-to/custom-fetch.md

@@ -0,0 +1,218 @@
+---
+title: Custom Fetch
+unstable: true
+---
+
+# Custom Fetch
+
+[MODES: framework]
+
+<docs-warning>This feature is experimental and may change in minor or patch releases. It is not supported in RSC Framework Mode.</docs-warning>
+
+The `unstable_fetch` prop on [`HydratedRouter`](../api/framework-routers/HydratedRouter) lets you customize the JavaScript-issued requests React Router makes for server loader/action data and lazy route discovery. Use it to add headers, customize fetch options, or apply a request policy based on the operation that initiated the request.
+
+This is a Framework Mode API. In Data Mode, you control fetching in your loaders/actions or through a [`dataStrategy`](./data-strategy#request-metadata-unstable).
+
+## Setup
+
+If you don't have an [`app/entry.client.tsx`](../api/framework-conventions/entry.client.tsx), reveal the default entry:
+
+```shellscript nonumber
+npx react-router reveal entry.client
+```
+
+Pass a custom implementation to `HydratedRouter`:
+
+```tsx filename=app/entry.client.tsx
+import { startTransition, StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+import {
+  HydratedRouter,
+  type unstable_RouterFetch,
+} from "react-router/dom";
+
+const customFetch: unstable_RouterFetch = (
+  request,
+  context,
+) => {
+  console.log(context.type, request.method, request.url);
+  return fetch(request);
+};
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <HydratedRouter unstable_fetch={customFetch} />
+    </StrictMode>,
+  );
+});
+```
+
+The callback receives a constructed `Request`, including its URL, headers, body, and abort signal, and must return a `Promise<Response>`. Pass that request to the browser's `fetch` to preserve those settings, including cancellation.
+
+`HydratedRouter` creates a singleton router and reads `unstable_fetch` only during initialization. Changing the prop later has no effect. If your implementation needs changing values such as authentication tokens, read current application state inside the callback instead of capturing values from a component render.
+
+## Request Context
+
+The [`unstable_RouterFetchContext`](https://api.reactrouter.com/v8/types/react-router.dom.unstable_RouterFetchContext.html) type is exported from `react-router/dom` and has the following shape:
+
+```ts
+import type { NavigationType } from "react-router";
+
+type unstable_RouterFetchContext =
+  | { type: "manifest" }
+  | {
+      type: "navigation";
+      fetcherKey: string | null;
+      navigationType: NavigationType;
+    }
+  | {
+      type: "initialization" | "fetcher" | "revalidation";
+      fetcherKey: string | null;
+      navigationType: null;
+    };
+```
+
+`type` identifies the operation that initiated the request:
+
+- `"manifest"`: Lazy route discovery requests. These have no `fetcherKey` or `navigationType`.
+- `"initialization"`: Data loading during router initialization, such as initial loader requests in API-only Mode.
+- `"navigation"`: Data requests initiated by a navigation, including action submissions and the subsequent loader revalidation.
+- `"fetcher"`: Requests initiated by a fetcher, including the loader revalidation after a fetcher action.
+- `"revalidation"`: Requests initiated by an explicit revalidation, such as `useRevalidator().revalidate()`.
+
+`fetcherKey` identifies the fetcher targeted by a data request, or is `null` for route loader/action requests. A fetcher reloaded as part of a navigation or explicit revalidation retains that initiating `type` and also includes its fetcher key. Fetchers reloaded after an initialization redirect likewise retain the `"initialization"` type and include their fetcher key.
+
+`navigationType` is `"PUSH"`, `"REPLACE"`, or `"POP"` for navigation-initiated data requests, including fetchers reloaded by that navigation. It is `null` for initialization, standalone fetcher operations, and explicit revalidation. This is the history action for the in-flight navigation, not the previously committed location.
+
+## Examples
+
+Each example below can be passed to `HydratedRouter` as its `unstable_fetch` prop.
+
+### Authentication and Custom Headers
+
+Read the current token at request time so token changes don't require replacing the callback:
+
+```ts
+import type { unstable_RouterFetch } from "react-router/dom";
+import { authStore } from "./auth";
+
+const customFetch: unstable_RouterFetch = (request) => {
+  let headers = new Headers(request.headers);
+  let token = authStore.getAccessToken();
+
+  if (token) {
+    headers.set("Authorization", `Bearer ${token}`);
+  }
+
+  headers.set("X-App-Version", "1.0");
+  return fetch(request, { headers });
+};
+```
+
+Here, `authStore` is your application's authentication store. Only send credentials to trusted origins. Adding custom headers to cross-origin requests may require a CORS preflight and corresponding server configuration.
+
+### Cross-Origin Credentials
+
+In [API-only Mode](../start/framework/rendering#using-a-separate-api-origin), use `unstable_apiServerOrigin` to configure a separate API origin. React Router applies that origin before calling your custom fetch, and also uses it for native data prefetches.
+
+The origin setting does not enable cross-origin cookies. If you need them, customize the credential policy for the trusted API origin:
+
+```ts
+import type { unstable_RouterFetch } from "react-router/dom";
+
+const customFetch: unstable_RouterFetch = (request) => {
+  let isApiRequest =
+    new URL(request.url).origin ===
+    "https://api.example.com";
+
+  return fetch(request, {
+    credentials: isApiRequest
+      ? "include"
+      : request.credentials,
+  });
+};
+```
+
+The API server must allow credentialed CORS requests from your client origin. Browser cookie policies still apply. Native data prefetches do not use this callback, so don't rely on it to configure their credentials.
+
+### Back/Forward Traversal Cache
+
+Use `navigationType` to prefer the browser's HTTP cache when navigating back or forward, while retaining the normal cache policy for other requests:
+
+```ts
+import type { unstable_RouterFetch } from "react-router/dom";
+
+const customFetch: unstable_RouterFetch = (
+  request,
+  context,
+) => {
+  let isTraversal =
+    import.meta.env.PROD &&
+    request.method === "GET" &&
+    context.type === "navigation" &&
+    context.navigationType === "POP";
+
+  return fetch(request, {
+    cache: isTraversal ? "force-cache" : "default",
+  });
+};
+```
+
+This example enables the policy in production only. It includes GET requests for fetchers reloaded by a back/forward navigation, but not standalone fetcher loads or explicit revalidations.
+
+The [`force-cache` policy](https://fetch.spec.whatwg.org/#concept-request-cache-mode) uses a matching HTTP cache entry even if it is stale, falling back to the network when no entry exists. Your server's responses must be cacheable; `Cache-Control: no-store` responses aren't stored.
+
+This is not a router-managed data cache. React Router still performs its request and response decoding, and this policy adds no mutation or authentication invalidation guarantees. Only use it when serving potentially stale data is appropriate for your application.
+
+### Retrying Safe Requests
+
+You can retry a safe GET after a network failure without retrying action submissions or canceled requests:
+
+```ts
+import type { unstable_RouterFetch } from "react-router/dom";
+
+const customFetch: unstable_RouterFetch = async (
+  request,
+) => {
+  if (request.method !== "GET") {
+    return fetch(request);
+  }
+
+  try {
+    return await fetch(request.clone());
+  } catch (error) {
+    if (
+      request.signal.aborted ||
+      (error instanceof Error &&
+        error.name === "AbortError")
+    ) {
+      throw error;
+    }
+
+    // Retry once, retaining the original abort signal.
+    return fetch(request);
+  }
+};
+```
+
+This assumes your GET endpoints are safe to repeat. It retries a rejected fetch, not HTTP error responses such as `500`. Don't automatically retry mutations: the server may have processed an action even when the client didn't receive its response.
+
+## Limitations
+
+### Requests Outside Custom Fetch
+
+Custom fetch does not intercept the initial document request, server-side loader execution, static assets, or fetches you write in your own application code, including in `clientLoader`/`clientAction`. Calls to their `serverLoader`/`serverAction` helpers do use custom fetch when they issue server data requests.
+
+Data prefetches from `<Link prefetch>`, `<NavLink prefetch>`, and [`PrefetchPageLinks`](../api/components/PrefetchPageLinks) use native `<link rel="prefetch">` elements and bypass custom fetch. If a request requires custom headers or other transformations, use `prefetch="none"` on links and avoid rendering `PrefetchPageLinks` for those routes.
+
+### Inspecting Request Bodies
+
+If you need a form field such as `intent` to choose request headers, read it from `await request.clone().formData()` for form-encoded submissions, then send the original request. Reading `request.formData()` directly consumes the body so it can't subsequently be sent unchanged.
+
+Only parse bodies with a compatible encoding. Cloning and reading a body can buffer data, so avoid doing this unnecessarily, especially for large file uploads. Adding headers or changing fetch options does not require reading the body.
+
+### Response Compatibility
+
+Return the response from `fetch` unchanged. You can inspect its status and headers, but you should not consume its body or try to decode, modify, or re-encode it. React Router handles response decoding and expects its manifest/data protocol, including Turbo Stream-encoded loader/action data.

package/docs/how-to/data-strategy.md

@@ -23,7 +23,9 @@ A custom `dataStrategy` receives the `loader`/`action` arguments (`request`, `pa
 
 - `matches`: An array of `DataStrategyMatch` instances for the routes matched by the current `request`
 - `runClientMiddleware`: A helper function to run the middleware for the matched routes
-- `fetcherKey`: The fetcher key if this is for a fetcher request and not a navigation
+- `fetcherKey`: The key of the fetcher targeted by this execution, or `null` for route loader/action executions. Fetchers reloaded by a navigation or explicit revalidation also provide their key.
+- `unstable_initiator`: The operation that initiated this execution (see [Request Metadata](#request-metadata-unstable))
+- `unstable_navigationType`: The history action for a navigation-initiated execution, or `null` for other executions
 
 A `DataStrategyMatch` is a normal route match plus a few additional fields:
 
@@ -77,6 +79,26 @@ interface DataStrategyResult {
 }
 ```
 
+### Request Metadata (unstable)
+
+<docs-warning>`unstable_initiator` and `unstable_navigationType` are experimental and may change in minor or patch releases.</docs-warning>
+
+`unstable_initiator` identifies why the data strategy is running:
+
+- `"initialization"`: Initial router data loading
+- `"navigation"`: A navigation, including action submissions and subsequent loader revalidation
+- `"fetcher"`: A fetcher operation, including loader revalidation after a fetcher action
+- `"revalidation"`: Explicit revalidation, such as `useRevalidator().revalidate()`
+- `"static"`: Execution by `createStaticHandler` on the server
+
+Requests that reload fetchers during a navigation or explicit revalidation retain that initiator while providing the targeted `fetcherKey`. Don't use `fetcherKey` alone to determine what initiated the execution.
+
+`unstable_navigationType` is `"PUSH"`, `"REPLACE"`, or `"POP"` for navigation-initiated executions, including fetchers reloaded by that navigation. It is `null` for initialization, standalone fetcher operations, explicit revalidation, and static handler executions. It describes the in-flight navigation rather than the previously committed location.
+
+You can use this metadata to choose a loading or caching policy. For example, a Data Mode `dataStrategy` can distinguish back/forward navigations with `unstable_initiator === "navigation" && unstable_navigationType === "POP"`. Your strategy remains responsible for executing the appropriate handlers and returning their results.
+
+Framework Mode exposes equivalent request metadata through [`unstable_fetch`](./custom-fetch#request-context), which customizes server requests without replacing loader/action execution.
+
 ### Calling Route Middleware
 
 If you are using `middleware` on your routes, you need to leverage the `callClientMiddleware` helper function to execute `middleware` around your handlers:

package/docs/how-to/fetchers.md

@@ -85,7 +85,7 @@ export default function Component() {
 
 ### 3. Submit the form
 
-If you submit the form now, the fetcher will call the action and revalidate the route data automatically.
+If you submit the form now, the fetcher will call the action and revalidate the route data automatically. See [Revalidation Optimization](./optimize-revalidation) to skip that reload for a route or a single submission.
 
 ### 4. Render pending state
 
@@ -305,3 +305,8 @@ Fetchers can be submitted programmatically with `fetcher.submit`:
 ```
 
 Note the input event's form is passed as the first argument to `fetcher.submit`. The fetcher will use that form to submit the request, reading its attributes and serializing the data from its elements.
+
+`fetcher.submit` accepts the same [`defaultShouldRevalidate`][fetcher-submit-options] option as [`<Form>`][form]. Pass `false` to skip loader revalidation for that submission. See [Revalidation Optimization](./optimize-revalidation) for how that interacts with route-level `shouldRevalidate`.
+
+[fetcher-submit-options]: https://api.reactrouter.com/v8/interfaces/react-router.FetcherSubmitOptions.html#defaultshouldrevalidate
+[form]: ../api/components/Form#defaultshouldrevalidate

package/docs/how-to/middleware.md

@@ -358,7 +358,9 @@ In theory, we could have leveraged [`AsyncLocalStorage`][asynclocalstorage] dire
 
 That said, this API still works great with React Router middleware and can be used in place of, or alongside of the `context` API:
 
-<docs-info>[`AsyncLocalStorage`][asynclocalstorage] is _especially_ powerful when using [React Server Components](../how-to/react-server-components) because it allows you to provide information from `middleware` to your Server Components and Server Actions because they run in the same server execution context 🤯</docs-info>
+<docs-info>[`AsyncLocalStorage`][asynclocalstorage] is _especially_ powerful when using [React Server Components](../how-to/react-server-components) because it allows you to provide information from `middleware` to your Server Components and route actions because they run in the same server execution context 🤯</docs-info>
+
+<docs-warning>Do not rely on route middleware to provide access control for React Server Functions. Server Functions are not inherently associated with a route, and a client can call the same Server Function through a URL with different middleware. Server Functions must perform all of their own access control checks. Use a route `action` instead when you want middleware-driven access control.</docs-warning>
 
 ```tsx filename=app/user-context.ts
 import { AsyncLocalStorage } from "node:async_hooks";
@@ -633,6 +635,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