react-router 8.3.0 → 8.4.0

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";

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

@@ -1,12 +1,185 @@
 ---
 title: Revalidation Optimization
-hidden: true
 ---
 
-[copy pasted]
+# Revalidation Optimization
 
-During client-side transitions, React Router will optimize reloading of routes that are already rendering, like not reloading layout routes that aren't changing. In other cases, like form submissions or search param changes, React Router doesn't know which routes need to be reloaded, so it reloads them all to be safe. This ensures your UI always stays in sync with the state on your server.
+[MODES: framework, data]
 
-This function lets apps further optimize by returning `false` when React Router is about to reload a route. If you define this function on a route module, React Router will defer to your function on every navigation and every revalidation after an action is called. Again, this makes it possible for your UI to get out of sync with your server if you do it wrong, so be careful.
+<br/>
+<br/>
 
-`fetcher.load` calls also revalidate, but because they load a specific URL, they don't have to worry about route param or URL search param revalidations. `fetcher.load`'s only revalidate by default after action submissions and explicit revalidation requests via [`useRevalidator`][use-revalidator].
+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
+affect that route's data, you can skip the reload.
+
+<docs-warning>
+Skipping revalidation can leave the UI out of sync with the server.
+Prefer targeting a specific action or navigation, and fall back to
+`defaultShouldRevalidate` instead of always returning `false`.
+</docs-warning>
+
+## Default behavior
+
+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))
+  - 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`])
+    - 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.
+
+Matched matched routes are handled independently - A child that skips
+revalidation does not skip any ancestor routes.
+
+[`fetcher.load`][use-fetcher] only revalidates by default after action
+submissions and explicit [`useRevalidator`][use-revalidator] calls, not
+on search-param or param-driven navigations.
+
+A plain `fetch()` to a [resource route][resource-routes] does not
+go through the router, so it does not revalidate loaders.
+
+## Skip a route with `shouldRevalidate`
+
+Export `shouldRevalidate` from the [route module][route-module]
+(Framework Mode) or set it on the [route object][data-mode]
+(Data Mode). Returning `false` skips **that route's** loader.
+
+```tsx filename=app/routes/dashboard.tsx
+// Framework Mode
+export function shouldRevalidate() {
+  return false;
+}
+```
+
+```tsx src/main.tsx
+// Data Mode
+createBrowserRouter([
+  {
+    path: "/dashboard",
+    loader: dashboardLoader,
+    shouldRevalidate: () => false,
+    Component: Dashboard,
+  },
+]);
+```
+
+Always returning `false` opts that route out of the default
+behavior completely, including cases you usually still want
+(param changes, explicit [`useRevalidator`][use-revalidator]).
+Prefer the conditional form below.
+
+## Opt out of specific requests
+
+Inspect
+[`ShouldRevalidateFunctionArgs`][should-revalidate-args]
+and return `defaultShouldRevalidate` for everything else.
+
+```tsx
+import type { ShouldRevalidateFunctionArgs } from "react-router";
+
+export function shouldRevalidate({
+  formMethod,
+  formAction,
+  defaultShouldRevalidate,
+}: ShouldRevalidateFunctionArgs) {
+  if (
+    formMethod === "POST" &&
+    formAction?.endsWith("/analytics")
+  ) {
+    return false;
+  }
+
+  return defaultShouldRevalidate;
+}
+```
+
+Other useful fields:
+
+- `formData`, `json`, `text` — the submission body
+- `actionResult`, `actionStatus` — the action's return value
+- `currentUrl`, `nextUrl`, `currentParams`, `nextParams` —
+  the navigation
+
+You can ignore search-param-only updates while still
+revalidating when the pathname changes:
+
+```tsx
+export function shouldRevalidate({
+  currentUrl,
+  nextUrl,
+  defaultShouldRevalidate,
+}: ShouldRevalidateFunctionArgs) {
+  if (currentUrl.pathname === nextUrl.pathname) {
+    return false;
+  }
+
+  return defaultShouldRevalidate;
+}
+```
+
+## Skip revalidation for one event
+
+Pass `defaultShouldRevalidate={false}` at the call site so you
+do not have to change every route file. This works on
+[`<Form>`][form], [`<Link>`][link], `<fetcher.Form>`, and as an
+option to [`useSubmit`][use-submit], `fetcher.submit`,
+[`useNavigate`][use-navigate], and
+[`useSearchParams`][use-search-params].
+
+```tsx
+import { Form, Link } from "react-router";
+
+<Link
+  to="/search?q=shoes"
+  defaultShouldRevalidate={false}
+>
+  Search Shoes
+</Link>
+
+<Form
+  method="post"
+  action="/analytics"
+  defaultShouldRevalidate={false}
+>
+  <button>Track Click</button>
+</Form>
+```
+
+```tsx
+fetcher.submit(
+  { intent: "save-progress" },
+  {
+    method: "post",
+    action: "/save-progress",
+    defaultShouldRevalidate: false,
+  },
+);
+```
+
+If a matched route does **not** export `shouldRevalidate`, this
+value is used directly for that loader. If it **does** export
+`shouldRevalidate`, the value is passed in as
+`defaultShouldRevalidate` and the route still has the final say.
+
+That is why a child `shouldRevalidate` that always returns
+`false` cannot hide a root reload after `fetcher.submit`. Either
+also opt `root` out for that case, or pass
+`defaultShouldRevalidate: false` at the call site when `root`
+has no `shouldRevalidate` of its own.
+
+[data-mode]: ../start/data/route-object#shouldrevalidate
+[form]: ../api/components/Form
+[link]: ../api/components/Link
+[resource-routes]: ./resource-routes
+[route-module]: ../start/framework/route-module#shouldrevalidate
+[should-revalidate-args]: https://api.reactrouter.com/v8/interfaces/react-router.ShouldRevalidateFunctionArgs.html
+[use-fetcher]: ../api/hooks/useFetcher
+[use-navigate]: ../api/hooks/useNavigate
+[use-revalidator]: ../api/hooks/useRevalidator
+[use-search-params]: ../api/hooks/useSearchParams
+[use-submit]: ../api/hooks/useSubmit

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

@@ -498,16 +498,39 @@ Using Server Components in loaders can be helpful for incremental adoption of RS
 
 [Server Functions][react-server-functions-doc] are a React feature that allow you to call async functions executed on the server. They're defined with the [`"use server"`][use-server-docs] directive.
 
+<docs-warning>
+
+Treat every Server Function as a public endpoint. The client controls both the
+Server Function identifier and request URL, so do not rely on route middleware
+for authentication or authorization. Server Functions must perform their own
+access control and input validation; use a route `action` when access control
+should be middleware-driven.
+
+</docs-warning>
+
 ```tsx
 "use server";
 
+import { unstable_getRequest as getRequest } from "react-router";
+import { requireUser } from "./auth.ts";
+
 export async function updateFavorite(formData: FormData) {
-  let movieId = formData.get("id");
+  let user = await requireUser(getRequest());
+  let movieId = Number(formData.get("id"));
   let intent = formData.get("intent");
+
+  if (
+    !Number.isSafeInteger(movieId) ||
+    movieId <= 0 ||
+    (intent !== "add" && intent !== "remove")
+  ) {
+    throw new Error("Invalid form submission");
+  }
+
   if (intent === "add") {
-    await addFavorite(Number(movieId));
+    await addFavorite(user.id, movieId);
   } else {
-    await removeFavorite(Number(movieId));
+    await removeFavorite(user.id, movieId);
   }
 }
 ```

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

@@ -66,6 +66,8 @@ export function action(_: Route.ActionArgs) {
 }
 ```
 
+Calling this `action` through [`<Form>`][form] or [`useFetcher`][fetcher] still revalidates matched UI loaders. A plain `fetch()` to the resource URL does not. See [Revalidation Optimization][optimize-revalidation] for more info.
+
 ## Return Types
 
 Resource Routes are flexible when it comes to the return type - you can return [`Response`][Response] instances or [`data()`][data] objects. A good general rule of thumb when deciding which type to use is:
@@ -124,3 +126,4 @@ export function action() {
 [form]: ../api/components/Form
 [await]: ../api/components/Await
 [error-boundary]: ../start/framework/route-module#errorboundary
+[optimize-revalidation]: ./optimize-revalidation

package/docs/start/data/actions.md

@@ -9,7 +9,7 @@ order: 5
 
 ## Defining Actions
 
-Data mutations are done through Route actions defined on the `action` property of a route object. When the action completes, all loader data on the page is revalidated to keep your UI in sync with the data without writing any code to do it.
+Data mutations are done through Route actions defined on the `action` property of a route object. When the action completes, all loader data on the page is revalidated to keep your UI in sync with the data without writing any code to do it. To skip some or all of those reloads, see [Revalidation Optimization][optimize-revalidation].
 
 ```tsx
 import { createBrowserRouter } from "react-router";
@@ -136,3 +136,4 @@ function Project() {
 Next: [Navigating](./navigating)
 
 [fetchers]: ../../how-to/fetchers
+[optimize-revalidation]: ../../how-to/optimize-revalidation

package/docs/start/data/route-object.md

@@ -188,7 +188,7 @@ export default function Items() {
 
 Loader data is automatically revalidated after certain events like navigations and form submissions.
 
-This hook enables you to opt in or out of the default revalidation behavior. The default behavior is nuanced to avoid calling loaders unnecessarily.
+This function lets you opt in or out of the default revalidation behavior **for this route's loader**. It does not skip parent or sibling loaders. The default behavior is nuanced to avoid calling loaders unnecessarily.
 
 A route loader is revalidated when:
 
@@ -201,21 +201,34 @@ By defining this function, you opt out of the default behavior completely and ca
 ```tsx
 import type { ShouldRevalidateFunctionArgs } from "react-router";
 
-function shouldRevalidate(
-  arg: ShouldRevalidateFunctionArgs,
-) {
-  return true; // false
+function shouldRevalidate({
+  formMethod,
+  formAction,
+  defaultShouldRevalidate,
+}: ShouldRevalidateFunctionArgs) {
+  if (
+    formMethod === "POST" &&
+    formAction?.endsWith("/analytics")
+  ) {
+    return false;
+  }
+
+  return defaultShouldRevalidate;
 }
 
 createBrowserRouter([
   {
     path: "/",
-    shouldRevalidate: shouldRevalidate,
+    shouldRevalidate,
     Component: MyRoute,
   },
 ]);
 ```
 
+To skip revalidation for a single `<Form>`, `<Link>`, `useSubmit`, or `fetcher.submit`, pass [`defaultShouldRevalidate={false}`][form-default-should-revalidate] at the call site. Routes without `shouldRevalidate` use that value directly.
+
+See [Revalidation Optimization][optimize-revalidation] for call-site opt-out, parent/child behavior, and more examples.
+
 [`ShouldRevalidateFunctionArgs` Reference Documentation ↗](https://api.reactrouter.com/v8/interfaces/react-router.ShouldRevalidateFunctionArgs.html)
 
 Please note the default behavior is different in [Framework Mode](../modes).
@@ -263,6 +276,8 @@ See also:
 
 Next: [Data Loading](./data-loading)
 
+[form-default-should-revalidate]: ../../api/components/Form#defaultshouldrevalidate
 [loader-params]: https://api.reactrouter.com/v8/interfaces/react-router.LoaderFunctionArgs
 [middleware]: ../../how-to/middleware
+[optimize-revalidation]: ../../how-to/optimize-revalidation
 [use-matches]: ../../api/hooks/useMatches

package/docs/start/framework/actions.md

@@ -9,7 +9,7 @@ order: 6
 
 ## Introduction
 
-Data mutations are done through Route actions. When the action completes, all loader data on the page is revalidated to keep your UI in sync with the data without writing any code to do it.
+Data mutations are done through Route actions. When the action completes, all loader data on the page is revalidated to keep your UI in sync with the data without writing any code to do it. To skip some or all of those reloads, see [Revalidation Optimization][optimize-revalidation].
 
 Route actions defined with `action` are only called on the server while actions defined with `clientAction` are run in the browser.
 
@@ -165,10 +165,12 @@ fetcher.submit(
 );
 ```
 
-See the [Using Fetchers][fetchers] guide for more information.
+`fetcher.submit` takes [`FetcherSubmitOptions`][fetcher-submit-options], including `defaultShouldRevalidate`. See the [Using Fetchers][fetchers] guide for more information.
 
 ---
 
 Next: [Navigating](./navigating)
 
 [fetchers]: ../../how-to/fetchers
+[fetcher-submit-options]: https://api.reactrouter.com/v8/interfaces/react-router.FetcherSubmitOptions.html#defaultshouldrevalidate
+[optimize-revalidation]: ../../how-to/optimize-revalidation

package/docs/start/framework/route-module.md

@@ -486,18 +486,43 @@ The meta of the last matching route is used, allowing you to override parent rou
 
 In framework mode with SSR, route loaders are automatically revalidated after all navigations and form submissions (this is different from [Data Mode][data-mode-should-revalidate]). This enables middleware and loaders to share a request context and optimize in different ways than they would in Data Mode.
 
-Defining this function allows you to opt out of revalidation for a route loader for navigations and form submissions.
+Defining this function allows you to opt out of revalidation for **this route's** loader. It does not skip parent or sibling loaders. After `fetcher.submit()`, `root` still revalidates unless it also opts out.
+
+Returning `false` for every call turns revalidation off for this loader:
+
+```tsx
+export function shouldRevalidate() {
+  return false;
+}
+```
+
+<docs-warning>
+Always returning `false` can leave this route's UI out of sync with the server. Prefer inspecting the arguments and falling back to `defaultShouldRevalidate`.
+</docs-warning>
 
 ```tsx
 import type { ShouldRevalidateFunctionArgs } from "react-router";
 
-export function shouldRevalidate(
-  arg: ShouldRevalidateFunctionArgs,
-) {
-  return true;
+export function shouldRevalidate({
+  formMethod,
+  formAction,
+  defaultShouldRevalidate,
+}: ShouldRevalidateFunctionArgs) {
+  if (
+    formMethod === "POST" &&
+    formAction?.endsWith("/analytics")
+  ) {
+    return false;
+  }
+
+  return defaultShouldRevalidate;
 }
 ```
 
+To skip revalidation for a single `<Form>`, `<Link>`, `useSubmit`, or `fetcher.submit` without changing every route file, pass [`defaultShouldRevalidate={false}`][form-default-should-revalidate] at the call site. Routes without a `shouldRevalidate` export use that value directly; routes that export one receive it as `defaultShouldRevalidate` and still decide.
+
+See [Revalidation Optimization][optimize-revalidation] for Framework vs Data Mode defaults, parent/child behavior, and more examples.
+
 When using [SPA Mode][spa-mode], there are no server loaders to call on navigations, so `shouldRevalidate` behaves the same as it does in [Data Mode][data-mode-should-revalidate].
 
 [`ShouldRevalidateFunctionArgs` Reference Documentation ↗](https://api.reactrouter.com/v8/interfaces/react-router.ShouldRevalidateFunctionArgs.html)
@@ -522,6 +547,8 @@ Next: [Rendering Strategies](./rendering)
 [meta-params]: https://api.reactrouter.com/v8/interfaces/react-router.MetaArgs
 [meta-function]: https://api.reactrouter.com/v8/types/react-router.MetaDescriptor.html
 [data-mode-should-revalidate]: ../data/route-object#shouldrevalidate
+[form-default-should-revalidate]: ../../api/components/Form#defaultshouldrevalidate
+[optimize-revalidation]: ../../how-to/optimize-revalidation
 [spa-mode]: ../../how-to/spa
 [client-data]: ../../how-to/client-data
 [styling]: ../../explanation/styling

package/docs/upgrading/future.md

@@ -106,6 +106,74 @@ export default {
 
 No code changes are required. If you run into dependency optimization issues after enabling this flag, remove the flag and restart the dev server.
 
+### `future.unstable_routePatternMatching`
+
+[MODES: data]
+
+<br/>
+<br/>
+
+**Background**
+
+This flag opts Data Routers into a new (and vastly more efficient) route matcher
+powered by [`@remix-run/route-pattern`](https://github.com/remix-run/remix/tree/main/packages/route-pattern).
+It supports the existing React Router path syntax and matching behavior, but may
+rank _slightly_ differently in some cases - please read the section below on
+potential ranking differences.
+
+👉 **Preload the Matcher and Enable the Flag**
+
+```ts
+import { createBrowserRouter } from "react-router";
+import { unstable_preloadRoutePattern } from "react-router/route-pattern";
+
+unstable_preloadRoutePattern();
+
+const router = createBrowserRouter(routes, {
+  future: {
+    unstable_routePatternMatching: true,
+  },
+});
+```
+
+The `react-router/route-pattern` sub-export statically imports the new matcher
+implementation. Tree-shaking bundlers remove it from applications that do not
+use the preload function. You must call the function before creating a router
+with the flag enabled - router creation will throw if the matcher has not been
+initialized. Initialization is synchronous, and repeated calls are safe.
+
+**Update your Code**
+
+No route configuration changes are required, but you should review any routes with
+overlapping patterns to ensure the new ranking behavior selects the intended route.
+The new implementation matches by positional specificity instead of aggregate
+segment scores. This means a route with a longer static prefix can rank above a
+route with more dynamic segments.
+
+For example, both of these routes match `/products/one/two/three`:
+
+```ts
+const routes = [
+  { path: "/products/*", id: "products" },
+  {
+    path: "/:first/:second/:third/:fourth",
+    id: "segments",
+  },
+];
+```
+
+The legacy matcher selects `segments` based on its aggregate segment score. The
+new matcher selects `products` because its static `products` segment is more
+specific than the dynamic `:first` segment in the same position.
+
+Once you enable this flag, use the `router.match()` when you need to match a
+location (this is currently marked private and will become stable at the same
+time this flag stabilizes). Standalone matching APIs such as `matchRoutes`,
+`matchPath`, and `useMatch` continue to use the legacy matcher and may return
+different matches than the router.
+
+Case-sensitive routes are not currently supported with this flag.
+
 [api-development-strategy]: ../community/api-development-strategy
 [governance]: https://github.com/remix-run/react-router/blob/main/GOVERNANCE.md#design-goals
 [unstable]: ../community/api-development-strategy#unstable-flags

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-router",
   "type": "module",
-  "version": "8.3.0",
+  "version": "8.4.0",
   "description": "Declarative routing for React",
   "keywords": [
     "react",
@@ -46,6 +46,15 @@
       "development": "./dist/development/dom-export.js",
       "default": "./dist/production/dom-export.js"
     },
+    "./route-pattern": {
+      "types": "./dist/production/route-pattern.d.ts",
+      "module-sync": {
+        "development": "./dist/development/route-pattern.js",
+        "default": "./dist/production/route-pattern.js"
+      },
+      "development": "./dist/development/route-pattern.js",
+      "default": "./dist/production/route-pattern.js"
+    },
     "./internal": {
       "types": "./dist/development/lib/types/internal.d.ts"
     },
@@ -76,6 +85,7 @@
     }
   },
   "dependencies": {
+    "@remix-run/route-pattern": "^0.22.1",
     "cookie-es": "^3.1.1"
   },
   "devDependencies": {