react-router 8.3.1 → 8.4.0

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.1",
+  "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": {