react-router 8.1.0 → 8.3.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # `react-router`
 
+## v8.3.0
+
+### Patch Changes
+
+- Encode path params in `href`/`generatePath` per RFC 3986 path-segment rules instead of `encodeURIComponent` ([#15310](https://github.com/remix-run/react-router/pull/15310))
+  - Characters that are valid literally in a path segment (`$ & + , ; = : @` — RFC 3986 `pchar`) are no longer percent-encoded, so values like a semver build `1.0.0+1` interpolate unchanged instead of becoming `1.0.0%2B1`
+  - Structural/unsafe characters (`/ ? # %`, whitespace, non-ASCII) are still escaped exactly as before
+- Use `crypto.randomUUID()` for `createMemorySessionStorage` session ids ([#15302](https://github.com/remix-run/react-router/pull/15302))
+  - `createMemorySessionStorage` is only intended for local development and testing - sessions are lost when the server restarts
+- Fix `NavLink` not applying its `pending` state when `to` has a trailing slash ([#15300](https://github.com/remix-run/react-router/pull/15300))
+- Preserve RSC route component metadata so routes with a `clientLoader` can skip unnecessary server requests once their components have rendered while still fetching missing server-rendered elements ([#15323](https://github.com/remix-run/react-router/pull/15323))
+- Harden RSC CSRF code paths ([#15311](https://github.com/remix-run/react-router/pull/15311))
+- Fix server crash (`TypeError: Invalid state: Unable to enqueue`) when a request is aborted while the RSC HTML stream has a pending flush ([#15286](https://github.com/remix-run/react-router/pull/15286))
+  - Handle cancellation of the `injectRSCPayload` readable side, clear the pending flush, and cancel the underlying RSC payload stream
+
+### Unstable Changes
+
+⚠️  _[Unstable features](https://reactrouter.com/community/api-development-strategy#unstable-flags) are not recommended for production use_
+
+- Detect stale RSC clients during lazy route discovery and reload the destination document ([#15318](https://github.com/remix-run/react-router/pull/15318))
+
+  #### Migration
+
+  Apps using the default RSC Framework entry do not need to make any changes. Apps with a custom `entry.rsc.tsx` should import the generated client version and pass it to `unstable_matchRSCServerRequest`:
+
+  ```tsx
+  import clientVersion from "virtual:react-router/unstable_rsc/client-version";
+
+  return unstable_matchRSCServerRequest({
+    // ...
+    clientVersion,
+  });
+  ```
+
+- Add CSP nonce support to RSC document rendering ([#15320](https://github.com/remix-run/react-router/pull/15320))
+
+  - Add `nonce` options to `unstable_routeRSCServerRequest` and `unstable_RSCStaticRouter`
+  - Forward the nonce to the HTML renderer and apply it to injected RSC payload scripts and nonce-aware framework components
+
+  To adopt nonce-based CSP, update your `entry.ssr.tsx` (run `react-router reveal entry.ssr` first in RSC Framework Mode) to generate a fresh nonce for each request. Pass it to `routeRSCServerRequest`, spread the `renderHTML` options into React's HTML renderer, pass `options.nonce` to `RSCStaticRouter`, and use the same nonce in the `Content-Security-Policy` response header:
+
+  ```tsx
+  const nonce = crypto.randomUUID();
+  const response = await routeRSCServerRequest({
+    request,
+    serverResponse,
+    createFromReadableStream,
+    nonce,
+    async renderHTML(getPayload, options) {
+      const payload = getPayload();
+      return renderHTMLToReadableStream(
+        <RSCStaticRouter getPayload={getPayload} nonce={options.nonce} />,
+        {
+          ...options,
+          bootstrapScriptContent,
+          formState: await payload.formState,
+          signal: request.signal,
+        },
+      );
+    },
+  });
+  response.headers.set(
+    "Content-Security-Policy",
+    `script-src 'self' 'nonce-${nonce}'`,
+  );
+  ```
+
+## v8.2.0
+
+### Patch Changes
+
+- Fix `href()` to properly stringify and URL-encode param values, matching `generatePath()` ([#15277](https://github.com/remix-run/react-router/pull/15277))
+  - splat params preserve path separators while encoding each segment individually
+- Fix dynamic param extraction for routes with optional static segments ([#15200](https://github.com/remix-run/react-router/pull/15200))
+  - When a route path contains optional static segments (e.g. `/school?/user/:id`), the internal regex's incorrectly shifted parameter indices resulting in incorrect parameter extraction
+  - Consecutive optional static segments (e.g. `/one?/two?`) were only partially handled
+- Preserve navigation blocker state through a revalidation ([#15246](https://github.com/remix-run/react-router/pull/15246))
+- Fix route ranking for dynamic parameters with static extension suffixes ([#15273](https://github.com/remix-run/react-router/pull/15273))
+  - These were not being detected as dynamic param segments and instead got incorrectly scored higher as a static segment
+  - This meant they could potentially tie truly static routes like `/sitemap.xml` and outrank them based on definition order
+  - These are now correctly identified as dynamic parameter segments and scored correctly
+- Use ReactFormState types instead of unknown ([#15263](https://github.com/remix-run/react-router/pull/15263))
+
 ## v8.1.0
 
 ### Minor Changes

package/dist/development/dom-export.js

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

package/dist/development/index-react-server-client.js

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

package/dist/development/index-react-server.d.ts

@@ -2,6 +2,7 @@
 import * as React from "react";
 import { CookieParseOptions, CookieParseOptions as CookieParseOptions$1, CookieSerializeOptions, CookieSerializeOptions as CookieSerializeOptions$1 } from "cookie-es";
 import { BrowserRouter, Form, HashRouter, Link, Links, MemoryRouter, Meta, NavLink, Navigate, Outlet, Route, Router, RouterProvider, Routes, ScrollRestoration, StaticRouter, StaticRouterProvider, unstable_HistoryRouter } from "react-router/internal/react-server-client";
+import { ReactFormState } from "react-dom/client";
 
 //#region lib/router/history.d.ts
 /**
@@ -2317,14 +2318,14 @@ type RSCRenderPayload = {
   type: "render";
   actionData: Record<string, any> | null;
   basename: string | undefined;
+  clientVersion?: string;
   errors: Record<string, any> | null;
   loaderData: Record<string, any>;
   location: Location;
   routeDiscovery: RouteDiscovery;
   matches: RSCRouteMatch[];
   patches?: Promise<RSCRouteManifest[]>;
-  nonce?: string;
-  formState?: unknown;
+  formState?: ReactFormState;
 };
 type RSCManifestPayload = {
   type: "manifest";
@@ -2350,7 +2351,7 @@ type RSCMatch = {
   payload: RSCPayload;
 };
 type DecodeActionFunction = (formData: FormData) => Promise<() => Promise<unknown>>;
-type DecodeFormStateFunction = (result: unknown, formData: FormData) => unknown;
+type DecodeFormStateFunction = (result: unknown, formData: FormData) => Promise<ReactFormState | undefined>;
 type DecodeReplyFunction = (reply: FormData | string, options: {
   temporaryReferences: unknown;
 }) => Promise<unknown[]>;
@@ -2420,6 +2421,8 @@ type RouteDiscovery = {
  * encoding the {@link unstable_RSCPayload}.
  * @param opts.loadServerAction Your `react-server-dom-xyz/server`'s
  * `loadServerAction` function, used to load a server action by ID.
+ * @param opts.clientVersion A version derived from the client build output used
+ * to detect stale clients during lazy route discovery.
  * @param opts.onError An optional error handler that will be called with any
  * errors that occur during the request processing.
  * @param opts.request The [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request)
@@ -2443,6 +2446,7 @@ declare function matchRSCServerRequest({
   loadServerAction,
   decodeAction,
   decodeFormState,
+  clientVersion,
   onError,
   request,
   routes,
@@ -2456,6 +2460,7 @@ declare function matchRSCServerRequest({
   decodeFormState?: DecodeFormStateFunction;
   requestContext?: RouterContextProvider;
   loadServerAction?: LoadServerActionFunction;
+  clientVersion?: string;
   onError?: (error: unknown) => void;
   request: Request;
   routes: RSCRouteConfigEntry[];
@@ -2489,14 +2494,30 @@ type Pages = Register extends {
 type Args = { [K in keyof Pages]: ToArgs<Pages[K]["params"]> };
 type ToArgs<Params extends Record<string, string | undefined>> = Equal<Params, {}> extends true ? [] : Partial<Params> extends Params ? [Params] | [] : [Params];
 /**
-  Returns a resolved URL path for the specified route.
-
-  ```tsx
-  const h = href("/:lang?/about", { lang: "en" })
-  // -> `/en/about`
-
-  <Link to={href("/products/:id", { id: "abc123" })} />
-  ```
+ * Returns a resolved URL path for the specified route.
+ *
+ * Param values are percent-encoded for use in a path segment: characters that
+ * would change the URL structure (`/`, `?`, `#`, `%`, whitespace, non-ASCII)
+ * are escaped, while characters that RFC 3986 allows literally in a path
+ * segment (`$ & + , ; = : @`) are kept as-is. Note this differs from query-string
+ * encoding (`encodeURIComponent`/`URLSearchParams`), where those characters are
+ * delimiters and must be escaped. Splat (`*`) values are encoded per segment,
+ * preserving `/` separators.
+ *
+ * See [RFC 3986 §3.3](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3)
+ *
+ * @example
+ * const h = href("/:lang?/about", { lang: "en" })
+ * // -> `/en/about`
+ *
+ * <Link to={href("/products/:id", { id: "abc123" })} />
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @param path The route path to resolve
+ * @param args The route params to use when resolving the path
+ * @returns The resolved URL path
  */
 declare function href<Path extends keyof Args>(path: Path, ...args: Args[Path]): string;
 //#endregion
@@ -2552,13 +2573,39 @@ interface Cookie {
 }
 /**
  * Creates a logical container for managing a browser cookie from the server.
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param name The name of the cookie.
+ * @param cookieOptions Options for parsing and serializing the cookie.
+ * @returns A {@link Cookie} object for parsing and serializing the cookie.
  */
 declare const createCookie: (name: string, cookieOptions?: CookieOptions) => Cookie;
+/**
+ * A function that determines whether a value is a React Router {@link Cookie}
+ * object.
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param object The value to check.
+ * @returns `true` if the value is a React Router {@link Cookie} object;
+ * otherwise, `false`.
+ */
 type IsCookieFunction = (object: any) => object is Cookie;
 /**
- * Returns true if an object is a Remix cookie container.
+ * Returns `true` if a value is a React Router {@link Cookie} object.
  *
- * @see https://remix.run/utils/cookies#iscookie
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param object The value to check.
+ * @returns `true` if the value is a React Router {@link Cookie} object;
+ * otherwise, `false`.
  */
 declare const isCookie: IsCookieFunction;
 //#endregion
@@ -2620,13 +2667,37 @@ type CreateSessionFunction = <Data = SessionData, FlashData = Data>(initialData?
  *
  * Note: This function is typically not invoked directly by application code.
  * Instead, use a `SessionStorage` object's `getSession` method.
+ *
+ * @category Utils
+ * @param initialData The initial data for the session.
+ * @param id The identifier for the session. Defaults to an empty string for a
+ * new session.
+ * @returns A new {@link Session} object.
  */
 declare const createSession: CreateSessionFunction;
+/**
+ * A function that determines whether a value is a React Router {@link Session}
+ * object.
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param object The value to check.
+ * @returns `true` if the value is a React Router {@link Session} object;
+ * otherwise, `false`.
+ */
 type IsSessionFunction = (object: any) => object is Session;
 /**
- * Returns true if an object is a React Router session.
+ * Returns `true` if a value is a React Router {@link Session} object.
  *
- * @see https://reactrouter.com/api/utils/isSession
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param object The value to check.
+ * @returns `true` if the value is a React Router {@link Session} object;
+ * otherwise, `false`.
  */
 declare const isSession: IsSessionFunction;
 /**
@@ -2693,6 +2764,11 @@ interface SessionIdStorageStrategy<Data = SessionData, FlashData = Data> {
  *
  * Note: This is a low-level API that should only be used if none of the
  * existing session storage options meet your requirements.
+ *
+ * @category Utils
+ * @param strategy The strategy used to store session identifiers and data.
+ * @returns A {@link SessionStorage} object that persists session data using the
+ * provided strategy.
  */
 declare function createSessionStorage<Data = SessionData, FlashData = Data>({
   cookie: cookieArg,
@@ -2718,6 +2794,14 @@ interface CookieSessionStorageOptions {
  * needed, and can help to simplify some load-balanced scenarios. However, it
  * also has the limitation that serialized session data may not exceed the
  * browser's maximum cookie size. Trade-offs!
+ *
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param options Options for creating the cookie-backed session storage.
+ * @returns A {@link SessionStorage} object that stores all session data in its
+ * cookie.
  */
 declare function createCookieSessionStorage<Data = SessionData, FlashData = Data>({
   cookie: cookieArg
@@ -2732,11 +2816,17 @@ interface MemorySessionStorageOptions {
   cookie?: SessionIdStorageStrategy["cookie"];
 }
 /**
- * Creates and returns a simple in-memory SessionStorage object, mostly useful
- * for testing and as a reference implementation.
+ * Creates and returns a simple in-memory SessionStorage object.
+ *
+ * Intended for local development and testing. It does not scale beyond a single
+ * process, and all session data is lost when the server process stops/restarts.
  *
- * Note: This storage does not scale beyond a single process, so it is not
- * suitable for most production scenarios.
+ * @public
+ * @category Utils
+ * @mode framework
+ * @mode data
+ * @param options Options for creating the in-memory session storage.
+ * @returns A {@link SessionStorage} object that stores session data in memory.
  */
 declare function createMemorySessionStorage<Data = SessionData, FlashData = Data>({
   cookie