react-router 7.16.0 → 8.0.0-pre.0

package/docs/explanation/form-vs-fetcher.md

@@ -0,0 +1,292 @@
+---
+title: Form vs. fetcher
+---
+
+# Form vs. fetcher
+
+[MODES: framework, data]
+
+## Overview
+
+Developing in React Router offers a rich set of tools that can sometimes overlap in functionality, creating a sense of ambiguity for newcomers. The key to effective development in React Router is understanding the nuances and appropriate use cases for each tool. This document seeks to provide clarity on when and why to use specific APIs.
+
+## APIs in Focus
+
+- [`<Form>`][form-component]
+- [`useFetcher`][use-fetcher]
+- [`useNavigation`][use-navigation]
+
+Understanding the distinctions and intersections of these APIs is vital for efficient and effective React Router development.
+
+## URL Considerations
+
+The primary criterion when choosing among these tools is whether you want the URL to change or not:
+
+- **URL Change Desired**: When navigating or transitioning between pages, or after certain actions like creating or deleting records. This ensures that the user's browser history accurately reflects their journey through your application.
+  - **Expected Behavior**: In many cases, when users hit the back button, they should be taken to the previous page. Other times the history entry may be replaced but the URL change is important nonetheless.
+
+- **No URL Change Desired**: For actions that don't significantly change the context or primary content of the current view. This might include updating individual fields or minor data manipulations that don't warrant a new URL or page reload. This also applies to loading data with fetchers for things like popovers, combo boxes, etc.
+
+### When the URL Should Change
+
+These actions typically reflect significant changes to the user's context or state:
+
+- **Creating a New Record**: After creating a new record, it's common to redirect users to a page dedicated to that new record, where they can view or further modify it.
+
+- **Deleting a Record**: If a user is on a page dedicated to a specific record and decides to delete it, the logical next step is to redirect them to a general page, such as a list of all records.
+
+For these cases, developers should consider using a combination of [`<Form>`][form-component] and [`useNavigation`][use-navigation]. These tools can be coordinated to handle form submission, invoke specific actions, retrieve action-related data through component props, and manage navigation respectively.
+
+### When the URL Shouldn't Change
+
+These actions are generally more subtle and don't require a context switch for the user:
+
+- **Updating a Single Field**: Maybe a user wants to change the name of an item in a list or update a specific property of a record. This action is minor and doesn't necessitate a new page or URL.
+
+- **Deleting a Record from a List**: In a list view, if a user deletes an item, they likely expect to remain on the list view, with that item no longer in the list.
+
+- **Creating a Record in a List View**: When adding a new item to a list, it often makes sense for the user to remain in that context, seeing their new item added to the list without a full page transition.
+
+- **Loading Data for a Popover or Combobox**: When loading data for a popover or combobox, the user's context remains unchanged. The data is loaded in the background and displayed in a small, self-contained UI element.
+
+For such actions, [`useFetcher`][use-fetcher] is the go-to API. It's versatile, combining functionalities of these APIs, and is perfectly suited for tasks where the URL should remain unchanged.
+
+## API Comparison
+
+As you can see, the two sets of APIs have a lot of similarities:
+
+| Navigation/URL API            | Fetcher API          |
+| ----------------------------- | -------------------- |
+| `<Form>`                      | `<fetcher.Form>`     |
+| `actionData` (component prop) | `fetcher.data`       |
+| `navigation.state`            | `fetcher.state`      |
+| `navigation.formAction`       | `fetcher.formAction` |
+| `navigation.formData`         | `fetcher.formData`   |
+
+## Examples
+
+### Creating a New Record
+
+```tsx filename=app/pages/new-recipe.tsx lines=[16,23-24,29]
+import {
+  Form,
+  redirect,
+  useNavigation,
+} from "react-router";
+import type { Route } from "./+types/new-recipe";
+
+export async function action({
+  request,
+}: Route.ActionArgs) {
+  const formData = await request.formData();
+  const errors = await validateRecipeFormData(formData);
+  if (errors) {
+    return { errors };
+  }
+  const recipe = await db.recipes.create(formData);
+  return redirect(`/recipes/${recipe.id}`);
+}
+
+export function NewRecipe({
+  actionData,
+}: Route.ComponentProps) {
+  const { errors } = actionData || {};
+  const navigation = useNavigation();
+  const isSubmitting =
+    navigation.formAction === "/recipes/new";
+
+  return (
+    <Form method="post">
+      <label>
+        Title: <input name="title" />
+        {errors?.title ? <span>{errors.title}</span> : null}
+      </label>
+      <label>
+        Ingredients: <textarea name="ingredients" />
+        {errors?.ingredients ? (
+          <span>{errors.ingredients}</span>
+        ) : null}
+      </label>
+      <label>
+        Directions: <textarea name="directions" />
+        {errors?.directions ? (
+          <span>{errors.directions}</span>
+        ) : null}
+      </label>
+      <button type="submit">
+        {isSubmitting ? "Saving..." : "Create Recipe"}
+      </button>
+    </Form>
+  );
+}
+```
+
+The example leverages [`<Form>`][form-component], component props, and [`useNavigation`][use-navigation] to facilitate an intuitive record creation process.
+
+Using `<Form>` ensures direct and logical navigation. After creating a record, the user is naturally guided to the new recipe's unique URL, reinforcing the outcome of their action.
+
+The component props bridge server and client, providing immediate feedback on submission issues. This quick response enables users to rectify any errors without hindrance.
+
+Lastly, `useNavigation` dynamically reflects the form's submission state. This subtle UI change, like toggling the button's label, assures users that their actions are being processed.
+
+Combined, these APIs offer a balanced blend of structured navigation and feedback.
+
+### Updating a Record
+
+Now consider we're looking at a list of recipes that have delete buttons on each item. When a user clicks the delete button, we want to delete the recipe from the database and remove it from the list without navigating away from the list.
+
+First, consider the basic route setup to get a list of recipes on the page:
+
+```tsx filename=app/pages/recipes.tsx
+import type { Route } from "./+types/recipes";
+
+export async function loader({
+  request,
+}: Route.LoaderArgs) {
+  return {
+    recipes: await db.recipes.findAll({ limit: 30 }),
+  };
+}
+
+export default function Recipes({
+  loaderData,
+}: Route.ComponentProps) {
+  const { recipes } = loaderData;
+  return (
+    <ul>
+      {recipes.map((recipe) => (
+        <RecipeListItem key={recipe.id} recipe={recipe} />
+      ))}
+    </ul>
+  );
+}
+```
+
+Now we'll look at the action that deletes a recipe and the component that renders each recipe in the list.
+
+```tsx filename=app/pages/recipes.tsx lines=[10,21,27]
+import { useFetcher } from "react-router";
+import type { Recipe } from "./recipe.server";
+import type { Route } from "./+types/recipes";
+
+export async function action({
+  request,
+}: Route.ActionArgs) {
+  const formData = await request.formData();
+  const id = formData.get("id");
+  await db.recipes.delete(id);
+  return { ok: true };
+}
+
+export default function Recipes() {
+  return (
+    // ...
+    // doesn't matter, somewhere it's using <RecipeListItem />
+  )
+}
+
+function RecipeListItem({ recipe }: { recipe: Recipe }) {
+  const fetcher = useFetcher();
+  const isDeleting = fetcher.state !== "idle";
+
+  return (
+    <li>
+      <h2>{recipe.title}</h2>
+      <fetcher.Form method="post">
+        <input type="hidden" name="id" value={recipe.id} />
+        <button disabled={isDeleting} type="submit">
+          {isDeleting ? "Deleting..." : "Delete"}
+        </button>
+      </fetcher.Form>
+    </li>
+  );
+}
+```
+
+Using [`useFetcher`][use-fetcher] in this scenario works perfectly. Instead of navigating away or refreshing the entire page, we want in-place updates. When a user deletes a recipe, the `action` is called and the fetcher manages the corresponding state transitions.
+
+The key advantage here is the maintenance of context. The user stays on the list when the deletion completes. The fetcher's state management capabilities are leveraged to give real-time feedback: it toggles between `"Deleting..."` and `"Delete"`, providing a clear indication of the ongoing process.
+
+Furthermore, with each `fetcher` having the autonomy to manage its own state, operations on individual list items become independent, ensuring that actions on one item don't affect the others (though revalidation of the page data is a shared concern covered in [Network Concurrency Management][network-concurrency-management]).
+
+In essence, `useFetcher` offers a seamless mechanism for actions that don't necessitate a change in the URL or navigation, enhancing the user experience by providing real-time feedback and context preservation.
+
+### Mark Article as Read
+
+Imagine you want to mark that an article has been read by the current user, after they've been on the page for a while and scrolled to the bottom. You could make a hook that looks something like this:
+
+```tsx
+import { useFetcher } from "react-router";
+
+function useMarkAsRead({ articleId, userId }) {
+  const marker = useFetcher();
+
+  useSpentSomeTimeHereAndScrolledToTheBottom(() => {
+    marker.submit(
+      { userId },
+      {
+        action: `/article/${articleId}/mark-as-read`,
+        method: "post",
+      },
+    );
+  });
+}
+```
+
+### User Avatar Details Popup
+
+Anytime you show the user avatar, you could put a hover effect that fetches data from a loader and displays it in a popup.
+
+```tsx filename=app/pages/user-details.tsx
+import { useState, useEffect } from "react";
+import { useFetcher } from "react-router";
+import type { Route } from "./+types/user-details";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  return await fakeDb.user.find({
+    where: { id: params.id },
+  });
+}
+
+type LoaderData = Route.ComponentProps["loaderData"];
+
+function UserAvatar({ partialUser }) {
+  const userDetails = useFetcher<LoaderData>();
+  const [showDetails, setShowDetails] = useState(false);
+
+  useEffect(() => {
+    if (
+      showDetails &&
+      userDetails.state === "idle" &&
+      !userDetails.data
+    ) {
+      userDetails.load(`/user-details/${partialUser.id}`);
+    }
+  }, [showDetails, userDetails, partialUser.id]);
+
+  return (
+    <div
+      onMouseEnter={() => setShowDetails(true)}
+      onMouseLeave={() => setShowDetails(false)}
+    >
+      <img src={partialUser.profileImageUrl} />
+      {showDetails ? (
+        userDetails.state === "idle" && userDetails.data ? (
+          <UserPopup user={userDetails.data} />
+        ) : (
+          <UserPopupLoading />
+        )
+      ) : null}
+    </div>
+  );
+}
+```
+
+## Conclusion
+
+React Router offers a range of tools to cater to varied developmental needs. While some functionalities might seem to overlap, each tool has been crafted with specific scenarios in mind. By understanding the intricacies and ideal applications of `<Form>`, `useFetcher`, and `useNavigation`, along with how data flows through component props, developers can create more intuitive, responsive, and user-friendly web applications.
+
+[form-component]: ../api/components/Form
+[use-fetcher]: ../api/hooks/useFetcher
+[use-navigation]: ../api/hooks/useNavigation
+[network-concurrency-management]: ./concurrency

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]: ../api/data-routers/loader
+[form_element]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form
+[form_component]: ../api/components/Form
+[action]: ../api/data-routers/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 -->