react-router 7.15.1 → 7.17.0

package/docs/explanation/hot-module-replacement.md

@@ -0,0 +1,137 @@
+---
+title: Hot Module Replacement
+---
+
+# Hot Module Replacement
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+Hot Module Replacement is a technique for updating modules in your app without needing to reload the page.
+It's a great developer experience, and React Router supports it when using Vite.
+
+HMR does its best to preserve browser state across updates.
+For example, let's say you have form within a modal and you fill out all the fields.
+As soon as you save any changes to the code, traditional live reload would hard refresh the page causing all of those fields to be reset.
+Every time you make a change, you'd have to open up the modal _again_ and fill out the form _again_.
+
+But with HMR, all of that state is preserved _across updates_.
+
+## React Fast Refresh
+
+React already has mechanisms for updating the DOM via its [virtual DOM][virtual-dom] in response to user interactions like clicking a button.
+Wouldn't it be great if React could handle updating the DOM in response to code changes too?
+
+That's exactly what [React Fast Refresh][react-refresh] is all about!
+Of course, React is all about components, not general JavaScript code, so React Fast Refresh only handles hot updates for exported React components.
+
+But React Fast Refresh does have some limitations that you should be aware of.
+
+### Class Component State
+
+React Fast Refresh does not preserve state for class components.
+This includes higher-order components that internally return classes:
+
+```tsx
+export class ComponentA extends Component {} // ❌
+
+export const ComponentB = HOC(ComponentC); // ❌ Won't work if HOC returns a class component
+
+export function ComponentD() {} // ✅
+export const ComponentE = () => {}; // ✅
+export default function ComponentF() {} // ✅
+```
+
+### Named Function Components
+
+Function components must be named, not anonymous, for React Fast Refresh to track changes:
+
+```tsx
+export default () => {}; // ❌
+export default function () {} // ❌
+
+const ComponentA = () => {};
+export default ComponentA; // ✅
+
+export default function ComponentB() {} // ✅
+```
+
+### Supported Exports
+
+React Fast Refresh can only handle component exports. While React Router manages [route exports like `action`, ` headers`, `links`, `loader`, and `meta`][route-module] for you, any user-defined exports will cause full reloads:
+
+```tsx
+// These exports are handled by the React Router Vite plugin
+// to be HMR-compatible
+export const meta = { title: "Home" }; // ✅
+export const links = [
+  { rel: "stylesheet", href: "style.css" },
+]; // ✅
+
+// These exports are removed by the React Router Vite plugin
+// so they never affect HMR
+export const headers = { "Cache-Control": "max-age=3600" }; // ✅
+export const loader = async () => {}; // ✅
+export const action = async () => {}; // ✅
+
+// This is not a route module export, nor a component export,
+// so it will cause a full reload for this route
+export const myValue = "some value"; // ❌
+
+export default function Route() {} // ✅
+```
+
+👆 Routes probably shouldn't be exporting random values like that anyway.
+If you want to reuse values across routes, stick them in their own non-route module:
+
+```ts filename=my-custom-value.ts
+export const myValue = "some value";
+```
+
+### Changing Hooks
+
+React Fast Refresh cannot track changes for a component when hooks are being added or removed from it, causing full reloads just for the next render. After the hooks have been updated, changes should result in hot updates again. For example, if you add a `useState` to your component, you may lose that component's local state for the next render.
+
+Additionally, if you are destructuring a hook's return value, React Fast Refresh will not be able to preserve state for the component if the destructured key is removed or renamed.
+For example:
+
+```tsx
+export default function Component({ loaderData }) {
+  const { pet } = useMyCustomHook();
+  return (
+    <div>
+      <input />
+      <p>My dog's name is {pet.name}!</p>
+    </div>
+  );
+}
+```
+
+If you change the key `pet` to `dog`:
+
+```diff
+ export default function Component() {
+-  const { pet } = useMyCustomHook();
++  const { dog } = useMyCustomHook();
+   return (
+     <div>
+       <input />
+-      <p>My dog's name is {pet.name}!</p>
++      <p>My dog's name is {dog.name}!</p>
+     </div>
+   );
+ }
+```
+
+then React Fast Refresh will not be able to preserve state `<input />` ❌.
+
+### Component Keys
+
+In some cases, React cannot distinguish between existing components being changed and new components being added. [React needs `key`s][react-keys] to disambiguate these cases and track changes when sibling elements are modified.
+
+[virtual-dom]: https://reactjs.org/docs/faq-internals.html#what-is-the-virtual-dom
+[react-refresh]: https://github.com/facebook/react/tree/main/packages/react-refresh
+[react-keys]: https://react.dev/learn/rendering-lists#why-does-react-need-keys
+[route-module]: ../start/framework/route-module

package/docs/explanation/hydration.md

@@ -0,0 +1,14 @@
+---
+title: Hydration
+hidden: true
+---
+
+There are a few nuances worth noting around the behavior of `HydrateFallback`:
+
+- It is only relevant on initial document request and hydration, and will not be rendered on any subsequent client-side navigations
+- It is only relevant when you are also setting [`clientLoader.hydrate=true`][hydrate-true] on a given route
+- It is also relevant if you do have a `clientLoader` without a server `loader`, as this implies `clientLoader.hydrate=true` since there is otherwise no loader data at all to return from `useLoaderData`
+  - Even if you do not specify a `HydrateFallback` in this case, React Router will not render your route component and will bubble up to any ancestor `HydrateFallback` component
+  - This is to ensure that `useLoaderData` remains "happy-path"
+  - Without a server `loader`, `useLoaderData` would return `undefined` in any rendered route components
+- You cannot render an `<Outlet/>` in a `HydrateFallback` because children routes can't be guaranteed to operate correctly since their ancestor loader data may not yet be available if they are running `clientLoader` functions on hydration (i.e., use cases such as `useRouteLoaderData()` or `useMatches()`)

package/docs/explanation/index-query-param.md

@@ -0,0 +1,86 @@
+---
+title: Index Query Param
+---
+
+# Index Query Param
+
+[MODES: framework, data]
+
+## Overview
+
+You may find a wild `?index` appearing in the URL of your app when submitting forms.
+
+Because of nested routes, multiple routes in your route hierarchy can match the URL. Unlike navigations where all matching route [`loader`][loader]s are called to build up the UI, when a [`form`][form_element] is submitted, _only one action is called_.
+
+Because index routes share the same URL as their parent, the `?index` param lets you disambiguate between the two.
+
+## Understanding Index Routes
+
+For example, consider the following route structure:
+
+```ts filename=app/routes.ts
+import {
+  type RouteConfig,
+  route,
+  index,
+} from "@react-router/dev/routes";
+
+export default [
+  route("projects", "./pages/projects.tsx", [
+    index("./pages/projects/index.tsx"),
+    route(":id", "./pages/projects/project.tsx"),
+  ]),
+] satisfies RouteConfig;
+```
+
+This creates two routes that match `/projects`:
+
+- The parent route (`./pages/projects.tsx`)
+- The index route (`./pages/projects/index.tsx`)
+
+## Form Submission Targeting
+
+For example, consider the following forms:
+
+```tsx
+<Form method="post" action="/projects" />
+<Form method="post" action="/projects?index" />
+```
+
+The `?index` param will submit to the index route; the action without the index param will submit to the parent route.
+
+When a [`<Form>`][form_component] is rendered in an index route without an [`action`][action], the `?index` param will automatically be appended so that the form posts to the index route. The following form, when submitted, will post to `/projects?index` because it is rendered in the context of the `projects` index route:
+
+```tsx filename=app/pages/projects/index.tsx
+function ProjectsIndex() {
+  return <Form method="post" />;
+}
+```
+
+If you moved the code to the project layout (`./pages/projects.tsx` in this example), it would instead post to `/projects`.
+
+This applies to `<Form>` and all of its cousins:
+
+```tsx
+function Component() {
+  const submit = useSubmit();
+  submit({}, { action: "/projects" });
+  submit({}, { action: "/projects?index" });
+}
+```
+
+```tsx
+function Component() {
+  const fetcher = useFetcher();
+  fetcher.submit({}, { action: "/projects" });
+  fetcher.submit({}, { action: "/projects?index" });
+  <fetcher.Form action="/projects" />;
+  <fetcher.Form action="/projects?index" />;
+  <fetcher.Form />; // defaults to the route in context
+}
+```
+
+[loader]: ../start/data/route-object#loader
+[form_element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form
+[form_component]: ../api/components/Form
+[action]: ../start/data/route-object#action

package/docs/explanation/index.md

@@ -0,0 +1,4 @@
+---
+title: Explanations
+order: 5
+---

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

@@ -0,0 +1,78 @@
+---
+title: Lazy Route Discovery
+---
+
+# Lazy Route Discovery
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+Lazy Route Discovery is a performance optimization that loads route information progressively as users navigate through your application, rather than loading the complete route manifest upfront.
+
+With Lazy Route Discovery enabled (the default), React Router sends only the routes needed for the initial server-side render in the manifest. As users navigate to new parts of your application, additional route information is fetched dynamically and added to the client-side manifest.
+
+The route manifest contains metadata about your routes (JavaScript/CSS imports, whether routes have `loaders`/`actions`, etc.) but not the actual route module implementations. This allows React Router to understand your application's structure without downloading unnecessary route information.
+
+## Route Discovery Process
+
+When a user navigates to a new route that isn't in the current manifest:
+
+1. **Route Discovery Request** - React Router makes a request to the internal `/__manifest` endpoint
+2. **Manifest Patch** - The server responds with the required route information
+3. **Route Loading** - React Router loads the necessary route modules and data
+4. **Navigation** - The user navigates to the new route
+
+## Eager Discovery Optimization
+
+To prevent navigation waterfalls, React Router implements eager route discovery. All [`<Link>`](../api/components/Link) and [`<NavLink>`](../api/components/NavLink) components rendered on the current page are automatically discovered via a batched request to the server.
+
+This discovery request typically completes before users click any links, making subsequent navigation feel synchronous even with lazy route discovery enabled.
+
+```tsx
+// Links are automatically discovered by default
+<Link to="/dashboard">Dashboard</Link>
+
+// Opt out of discovery for specific links
+<Link to="/admin" discover="none">Admin</Link>
+```
+
+## Performance Benefits
+
+Lazy Route Discovery provides several performance improvements:
+
+- **Faster Initial Load** - Smaller initial bundle size by excluding unused route metadata
+- **Reduced Memory Usage** - Route information is loaded only when needed
+- **Scalability** - Applications with hundreds of routes see more significant benefits
+
+## Configuration
+
+You can configure route discovery behavior in your `react-router.config.ts`:
+
+```tsx filename=react-router.config.ts
+export default {
+  // Default: lazy discovery with /__manifest endpoint
+  routeDiscovery: {
+    mode: "lazy",
+    manifestPath: "/__manifest",
+  },
+
+  // Custom manifest path (useful for multiple apps on same domain)
+  routeDiscovery: {
+    mode: "lazy",
+    manifestPath: "/my-app-manifest",
+  },
+
+  // Disable lazy discovery (include all routes initially)
+  routeDiscovery: { mode: "initial" },
+} satisfies Config;
+```
+
+## Deployment Considerations
+
+When using lazy route discovery, ensure your deployment setup handles manifest requests properly:
+
+- **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

package/docs/explanation/location.md

@@ -0,0 +1,6 @@
+---
+title: Location Object
+hidden: true
+---
+
+<!-- put some stuff about what it is and how it can be used, probably good opportunity for a couple how-tos as well with scroll restoration, etc -->

package/docs/explanation/progressive-enhancement.md

@@ -0,0 +1,150 @@
+---
+title: Progressive Enhancement
+---
+
+# Progressive Enhancement
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+> Progressive enhancement is a strategy in web design that puts emphasis on web content first, allowing everyone to access the basic content and functionality of a web page, whilst users with additional browser features or faster Internet access receive the enhanced version instead.
+>
+> <cite>- [Wikipedia][wikipedia]</cite>
+
+When using React Router with Server-Side Rendering (the default in framework mode), you can automatically leverage the benefits of progressive enhancement.
+
+## Why Progressive Enhancement Matters
+
+Coined in 2003 by Steven Champeon & Nick Finck, the phrase emerged during a time of varied CSS and JavaScript support across different browsers, with many users actually browsing the web with JavaScript disabled.
+
+Today, we are fortunate to develop for a much more consistent web and where the majority of users have JavaScript enabled.
+
+However, we still believe in the core principles of progressive enhancement in React Router. It leads to fast and resilient apps with simple development workflows.
+
+**Performance**: While it's easy to think that only 5% of your users have slow connections, the reality is that 100% of your users have slow connections 5% of the time.
+
+**Resilience**: Everybody has JavaScript disabled until it's loaded.
+
+**Simplicity**: Building your apps in a progressively enhanced way with React Router is actually simpler than building a traditional SPA.
+
+## Performance
+
+Server rendering allows your app to do more things in parallel than a typical [Single Page App (SPA)][spa], making the initial loading experience and subsequent navigations faster.
+
+Typical SPAs send a blank document and only start doing work when JavaScript has loaded:
+
+```
+HTML        |---|
+JavaScript      |---------|
+Data                      |---------------|
+                            page rendered 👆
+```
+
+A React Router app can start doing work the moment the request hits the server and stream the response so that the browser can start downloading JavaScript, other assets, and data in parallel:
+
+```
+               👇 first byte
+HTML        |---|-----------|
+JavaScript      |---------|
+Data        |---------------|
+              page rendered 👆
+```
+
+## Resilience and Accessibility
+
+While your users probably don't browse the web with JavaScript disabled, everybody uses the websites without JavaScript before it finishes loading. React Router embraces progressive enhancement by building on top of HTML, allowing you to build your app in a way that works without JavaScript, and then layer on JavaScript to enhance the experience.
+
+The simplest case is a `<Link to="/account">`. These render an `<a href="/account">` tag that works without JavaScript. When JavaScript loads, React Router will intercept clicks and handle the navigation with client side routing. This gives you more control over the UX instead of just spinning favicons in the browser tab--but it works either way.
+
+Now consider a simple add to cart button:
+
+```tsx
+export function AddToCart({ id }) {
+  return (
+    <Form method="post" action="/add-to-cart">
+      <input type="hidden" name="id" value={id} />
+      <button type="submit">Add To Cart</button>
+    </Form>
+  );
+}
+```
+
+Whether JavaScript has loaded or not doesn't matter, this button will add the product to the cart.
+
+When JavaScript loads, React Router will intercept the form submission and handle it client side. This allows you to add your own pending UI, or other client side behavior.
+
+## Simplicity
+
+When you start to rely on basic features of the web like HTML and URLs, you will find that you reach for client side state and state management much less.
+
+Consider the button from before, with no fundamental change to the code, we can pepper in some client side behavior:
+
+```tsx lines=[1,4,7,10-12,14]
+import { useFetcher } from "react-router";
+
+export function AddToCart({ id }) {
+  const fetcher = useFetcher();
+
+  return (
+    <fetcher.Form method="post" action="/add-to-cart">
+      <input name="id" value={id} />
+      <button type="submit">
+        {fetcher.state === "submitting"
+          ? "Adding..."
+          : "Add To Cart"}
+      </button>
+    </fetcher.Form>
+  );
+}
+```
+
+This feature continues to work the very same as it did before when JavaScript is loading, but once JavaScript loads:
+
+- `useFetcher` no longer causes a navigation like `<Form>` does, so the user can stay on the same page and keep shopping
+- The app code determines the pending UI instead of spinning favicons in the browser
+
+It's not about building it two different ways–once for JavaScript and once without–it's about building it in iterations. Start with the simplest version of the feature and ship it; then iterate to an enhanced user experience.
+
+Not only will the user get a progressively enhanced experience, but the app developer gets to "progressively enhance" the UI without changing the fundamental design of the feature.
+
+Another example where progressive enhancement leads to simplicity is with the URL. When you start with a URL, you don't need to worry about client side state management. You can just use the URL as the source of truth for the UI.
+
+```tsx
+export function SearchBox() {
+  return (
+    <Form method="get" action="/search">
+      <input type="search" name="query" />
+      <SearchIcon />
+    </Form>
+  );
+}
+```
+
+This component doesn't need any state management. It just renders a form that submits to `/search`. When JavaScript loads, React Router will intercept the form submission and handle it client side. Here's the next iteration:
+
+```tsx lines=[1,4-6,11]
+import { useNavigation } from "react-router";
+
+export function SearchBox() {
+  const navigation = useNavigation();
+  const isSearching =
+    navigation.location.pathname === "/search";
+
+  return (
+    <Form method="get" action="/search">
+      <input type="search" name="query" />
+      {isSearching ? <Spinner /> : <SearchIcon />}
+    </Form>
+  );
+}
+```
+
+No fundamental change in architecture, simply a progressive enhancement for both the user and the code.
+
+See also: [State Management][state_management]
+
+[wikipedia]: https://en.wikipedia.org/wiki/Progressive_enhancement
+[spa]: ../how-to/spa
+[state_management]: ./state-management

package/docs/explanation/race-conditions.md

@@ -0,0 +1,88 @@
+---
+title: Race Conditions
+---
+
+# Race Conditions
+
+[MODES: framework, data]
+
+<br/>
+<br/>
+
+While impossible to eliminate every possible race condition in your application, React Router automatically handles the most common race conditions found in web user interfaces.
+
+## Browser Behavior
+
+React Router's handling of network concurrency is heavily inspired by the behavior of web browsers when processing documents.
+
+Consider clicking a link to a new document, and then clicking a different link before the new page has finished loading. The browser will:
+
+1. cancel the first request
+2. immediately process the new navigation
+
+The same behavior applies to form submissions. When a pending form submission is interrupted by a new one, the first is canceled and the new submission is immediately processed.
+
+## React Router Behavior
+
+Like the browser, interrupted navigations with links and form submissions will cancel in flight data requests and immediately process the new event.
+
+Fetchers are a bit more nuanced since they are not singleton events like navigation. Fetchers can't interrupt other fetcher instances, but they can interrupt themselves and the behavior is the same as everything else: cancel the interrupted request and immediately process the new one.
+
+Fetchers do, however, interact with each other when it comes to revalidation. After a fetcher's action request returns to the browser, a revalidation for all page data is sent. This means multiple revalidation requests can be in-flight at the same time. React Router will commit all "fresh" revalidation responses and cancel any stale requests. A stale request is any request that started _earlier_ than one that has returned.
+
+This management of the network prevents the most common UI bugs caused by network race conditions.
+
+Since networks are unpredictable, and your server still processes these cancelled requests, your backend may still experience race conditions and have potential data integrity issues. These risks are the same risks as using default browser behavior with plain HTML `<forms>`, which we consider to be low, and outside the scope of React Router.
+
+## Practical Benefits
+
+Consider building a type-ahead combobox. As the user types, you send a request to the server. As they type each new character you send a new request. It's important to not show the user results for a value that's not in the text field anymore.
+
+When using a fetcher, this is automatically managed for you. Consider this pseudo-code:
+
+```tsx
+// route("/city-search", "./search-cities.ts")
+export async function loader({ request }) {
+  const { searchParams } = new URL(request.url);
+  return searchCities(searchParams.get("q"));
+}
+```
+
+```tsx
+export function CitySearchCombobox() {
+  const fetcher = useFetcher();
+
+  return (
+    <fetcher.Form action="/city-search">
+      <Combobox aria-label="Cities">
+        <ComboboxInput
+          name="q"
+          onChange={(event) =>
+            // submit the form onChange to get the list of cities
+            fetcher.submit(event.target.form)
+          }
+        />
+
+        {fetcher.data ? (
+          <ComboboxPopover className="shadow-popup">
+            {fetcher.data.length > 0 ? (
+              <ComboboxList>
+                {fetcher.data.map((city) => (
+                  <ComboboxOption
+                    key={city.id}
+                    value={city.name}
+                  />
+                ))}
+              </ComboboxList>
+            ) : (
+              <span>No results found</span>
+            )}
+          </ComboboxPopover>
+        ) : null}
+      </Combobox>
+    </fetcher.Form>
+  );
+}
+```
+
+Calls to `fetcher.submit` will cancel pending requests on that fetcher automatically. This ensures you never show the user results for a request for a different input value.