react-router 7.16.0 → 7.17.0

package/docs/start/framework/routing.md

@@ -0,0 +1,362 @@
+---
+title: Routing
+order: 2
+---
+
+# Routing
+
+[MODES: framework]
+
+## Configuring Routes
+
+Routes are configured in `app/routes.ts`. Each route has two required parts: a URL pattern to match the URL, and a file path to the route module that defines its behavior.
+
+```ts filename=app/routes.ts
+import {
+  type RouteConfig,
+  route,
+} from "@react-router/dev/routes";
+
+export default [
+  route("some/path", "./some/file.tsx"),
+  // pattern ^           ^ module file
+] satisfies RouteConfig;
+```
+
+Here is a larger sample route config:
+
+```ts filename=app/routes.ts
+import {
+  type RouteConfig,
+  route,
+  index,
+  layout,
+  prefix,
+} from "@react-router/dev/routes";
+
+export default [
+  index("./home.tsx"),
+  route("about", "./about.tsx"),
+
+  layout("./auth/layout.tsx", [
+    route("login", "./auth/login.tsx"),
+    route("register", "./auth/register.tsx"),
+  ]),
+
+  ...prefix("concerts", [
+    index("./concerts/home.tsx"),
+    route(":city", "./concerts/city.tsx"),
+    route("trending", "./concerts/trending.tsx"),
+  ]),
+] satisfies RouteConfig;
+```
+
+If you prefer to define your routes via file naming conventions rather than configuration, the `@react-router/fs-routes` package provides a [file system routing convention][file-route-conventions]. You can even combine different routing conventions if you like:
+
+```ts filename=app/routes.ts
+import {
+  type RouteConfig,
+  route,
+} from "@react-router/dev/routes";
+import { flatRoutes } from "@react-router/fs-routes";
+
+export default [
+  route("/", "./home.tsx"),
+
+  ...(await flatRoutes()),
+] satisfies RouteConfig;
+```
+
+## Route Modules
+
+The files referenced in `routes.ts` define each route's behavior:
+
+```tsx filename=app/routes.ts
+route("teams/:teamId", "./team.tsx"),
+//           route module ^^^^^^^^
+```
+
+Here's a sample route module:
+
+```tsx filename=app/team.tsx
+// provides type safety/inference
+import type { Route } from "./+types/team";
+
+// provides `loaderData` to the component
+export async function loader({ params }: Route.LoaderArgs) {
+  let team = await fetchTeam(params.teamId);
+  return { name: team.name };
+}
+
+// renders after the loader is done
+export default function Component({
+  loaderData,
+}: Route.ComponentProps) {
+  return <h1>{loaderData.name}</h1>;
+}
+```
+
+Route modules have more features like actions, headers, and error boundaries, but they will be covered in the next guide: [Route Modules](./route-module)
+
+## Nested Routes
+
+Routes can be nested inside parent routes.
+
+```ts filename=app/routes.ts
+import {
+  type RouteConfig,
+  route,
+  index,
+} from "@react-router/dev/routes";
+
+export default [
+  // parent route
+  route("dashboard", "./dashboard.tsx", [
+    // child routes
+    index("./home.tsx"),
+    route("settings", "./settings.tsx"),
+  ]),
+] satisfies RouteConfig;
+```
+
+The path of the parent is automatically included in the child, so this config creates both `"/dashboard"` and `"/dashboard/settings"` URLs.
+
+Child routes are rendered through the `<Outlet/>` in the parent route.
+
+```tsx filename=app/dashboard.tsx
+import { Outlet } from "react-router";
+
+export default function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      {/* will either be home.tsx or settings.tsx */}
+      <Outlet />
+    </div>
+  );
+}
+```
+
+## Root Route
+
+Every route in `routes.ts` is nested inside the special `app/root.tsx` module.
+
+## Layout Routes
+
+Using `layout`, layout routes create new nesting for their children, but they don't add any segments to the URL. It's like the root route but they can be added at any level.
+
+```tsx filename=app/routes.ts lines=[10,16]
+import {
+  type RouteConfig,
+  route,
+  layout,
+  index,
+  prefix,
+} from "@react-router/dev/routes";
+
+export default [
+  layout("./marketing/layout.tsx", [
+    index("./marketing/home.tsx"),
+    route("contact", "./marketing/contact.tsx"),
+  ]),
+  ...prefix("projects", [
+    index("./projects/home.tsx"),
+    layout("./projects/project-layout.tsx", [
+      route(":pid", "./projects/project.tsx"),
+      route(":pid/edit", "./projects/edit-project.tsx"),
+    ]),
+  ]),
+] satisfies RouteConfig;
+```
+
+Note that:
+
+- `home.tsx` and `contact.tsx` will be rendered into the `marketing/layout.tsx` outlet without creating any new URL paths
+- `project.tsx` and `edit-project.tsx` will be rendered into the `projects/project-layout.tsx` outlet at `/projects/:pid` and `/projects/:pid/edit` while `projects/home.tsx` will not.
+
+## Index Routes
+
+```ts
+index(componentFile),
+```
+
+Index routes render into their parent's [Outlet][outlet] at their parent's URL (like a default child route).
+
+```ts filename=app/routes.ts
+import {
+  type RouteConfig,
+  route,
+  index,
+} from "@react-router/dev/routes";
+
+export default [
+  // renders into the root.tsx Outlet at /
+  index("./home.tsx"),
+  route("dashboard", "./dashboard.tsx", [
+    // renders into the dashboard.tsx Outlet at /dashboard
+    index("./dashboard-home.tsx"),
+    route("settings", "./dashboard-settings.tsx"),
+  ]),
+] satisfies RouteConfig;
+```
+
+Note that index routes can't have children.
+
+## Route Prefixes
+
+Using `prefix`, you can add a path prefix to a set of routes without needing to introduce a parent route.
+
+```tsx filename=app/routes.ts lines=[14]
+import {
+  type RouteConfig,
+  route,
+  layout,
+  index,
+  prefix,
+} from "@react-router/dev/routes";
+
+export default [
+  layout("./marketing/layout.tsx", [
+    index("./marketing/home.tsx"),
+    route("contact", "./marketing/contact.tsx"),
+  ]),
+  ...prefix("projects", [
+    index("./projects/home.tsx"),
+    layout("./projects/project-layout.tsx", [
+      route(":pid", "./projects/project.tsx"),
+      route(":pid/edit", "./projects/edit-project.tsx"),
+    ]),
+  ]),
+] satisfies RouteConfig;
+```
+
+Note that this does not introduce a new route into the route tree. Instead, it merely modifies the paths of its children.
+
+For example, these two sets of routes are equivalent:
+
+```ts filename=app/routes.ts
+// This usage of `prefix`...
+prefix("parent", [
+  route("child1", "./child1.tsx"),
+  route("child2", "./child2.tsx"),
+])
+
+// ...is equivalent to this:
+[
+  route("parent/child1", "./child1.tsx"),
+  route("parent/child2", "./child2.tsx"),
+]
+```
+
+## Dynamic Segments
+
+If a path segment starts with `:` then it becomes a "dynamic segment". When the route matches the URL, the dynamic segment will be parsed from the URL and provided as `params` to other router APIs.
+
+```ts filename=app/routes.ts
+route("teams/:teamId", "./team.tsx"),
+```
+
+```tsx filename=app/team.tsx
+import type { Route } from "./+types/team";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  //                           ^? { teamId: string }
+}
+
+export default function Component({
+  params,
+}: Route.ComponentProps) {
+  params.teamId;
+  //        ^ string
+}
+```
+
+You can have multiple dynamic segments in one route path:
+
+```ts filename=app/routes.ts
+route("c/:categoryId/p/:productId", "./product.tsx"),
+```
+
+```tsx filename=app/product.tsx
+import type { Route } from "./+types/product";
+
+async function loader({ params }: LoaderArgs) {
+  //                    ^? { categoryId: string; productId: string }
+}
+```
+
+## Optional Segments
+
+You can make a route segment optional by adding a `?` to the end of the segment.
+
+```ts filename=app/routes.ts
+route(":lang?/categories", "./categories.tsx"),
+```
+
+You can have optional static segments, too:
+
+```ts filename=app/routes.ts
+route("users/:userId/edit?", "./user.tsx");
+```
+
+## Splats
+
+Also known as "catchall" and "star" segments. If a route path pattern ends with `/*` then it will match any characters following the `/`, including other `/` characters.
+
+```ts filename=app/routes.ts
+route("files/*", "./files.tsx"),
+```
+
+```tsx filename=app/files.tsx
+export async function loader({ params }: Route.LoaderArgs) {
+  // params["*"] will contain the remaining URL after files/
+}
+```
+
+You can destructure the `*`, you just have to assign it a new name. A common name is `splat`:
+
+```tsx
+const { "*": splat } = params;
+```
+
+You can also use a splat to catch requests that don't match any route:
+
+```ts filename=app/routes.ts
+route("*", "./catchall.tsx"); // catchall route,
+```
+
+```tsx filename=app/catchall.tsx
+export function loader() {
+  throw new Response("Page not found", { status: 404 });
+}
+```
+
+## Component Routes
+
+You can also use components that match the URL to elements anywhere in the component tree:
+
+```tsx
+import { Routes, Route } from "react-router";
+
+function Wizard() {
+  return (
+    <div>
+      <h1>Some Wizard with Steps</h1>
+      <Routes>
+        <Route index element={<StepOne />} />
+        <Route path="step-2" element={<StepTwo />} />
+        <Route path="step-3" element={<StepThree />} />
+      </Routes>
+    </div>
+  );
+}
+```
+
+Note that these routes do not participate in data loading, actions, code splitting, or any other route module features, so their use cases are more limited than those of the route module.
+
+---
+
+Next: [Route Module](./route-module)
+
+[file-route-conventions]: ../../how-to/file-route-conventions
+[outlet]: https://api.reactrouter.com/v7/functions/react-router.Outlet.html

package/docs/start/framework/testing.md

@@ -0,0 +1,133 @@
+---
+title: Testing
+order: 9
+---
+
+# Testing
+
+[MODES: framework, data]
+
+## Introduction
+
+When components use things like `useLoaderData`, `<Link>`, etc, they are required to be rendered in context of a React Router app. The `createRoutesStub` function creates that context to test components in isolation.
+
+Consider a login form component that relies on `useActionData`
+
+```tsx
+import { useActionData } from "react-router";
+
+export function LoginForm() {
+  const actionData = useActionData();
+  const errors = actionData?.errors;
+  return (
+    <Form method="post">
+      <label>
+        <input type="text" name="username" />
+        {errors?.username && <div>{errors.username}</div>}
+      </label>
+
+      <label>
+        <input type="password" name="password" />
+        {errors?.password && <div>{errors.password}</div>}
+      </label>
+
+      <button type="submit">Login</button>
+    </Form>
+  );
+}
+```
+
+We can test this component with `createRoutesStub`. It takes an array of objects that resemble route modules with loaders, actions, and components.
+
+```tsx
+import { createRoutesStub } from "react-router";
+import {
+  render,
+  screen,
+  waitFor,
+} from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { LoginForm } from "./LoginForm";
+
+test("LoginForm renders error messages", async () => {
+  const USER_MESSAGE = "Username is required";
+  const PASSWORD_MESSAGE = "Password is required";
+
+  const Stub = createRoutesStub([
+    {
+      path: "/login",
+      Component: LoginForm,
+      action() {
+        return {
+          errors: {
+            username: USER_MESSAGE,
+            password: PASSWORD_MESSAGE,
+          },
+        };
+      },
+    },
+  ]);
+
+  // render the app stub at "/login"
+  render(<Stub initialEntries={["/login"]} />);
+
+  // simulate interactions
+  userEvent.click(screen.getByText("Login"));
+  await waitFor(() => screen.findByText(USER_MESSAGE));
+  await waitFor(() => screen.findByText(PASSWORD_MESSAGE));
+});
+```
+
+## Using with Framework Mode Types
+
+It's important to note that `createRoutesStub` is designed for _unit_ testing of reusable components in your application that rely on contextual router information (i.e., `loaderData`, `actionData`, `matches`). These components usually obtain this information via the hooks (`useLoaderData`, `useActionData`, `useMatches`) or via props passed down from the ancestor route component. We **strongly** recommend limiting your usage of `createRoutesStub` to unit testing of these types of reusable components.
+
+`createRoutesStub` is _not designed_ for (and is arguably incompatible with) direct testing of Route components using the [`Route.\*`](../../explanation/type-safety) types available in Framework Mode. This is because the `Route.*` types are derived from your actual application - including the real `loader`/`action` functions as well as the structure of your route tree structure (which defines the `matches` type). When you use `createRoutesStub`, you are providing stubbed values for `loaderData`, `actionData`, and even your `matches` based on the route tree you pass to `createRoutesStub`. Therefore, the types won't align with the `Route.*` types and you'll get type issues trying to use a route component in a route stub.
+
+```tsx filename=routes/login.tsx
+export default function Login({
+  actionData,
+}: Route.ComponentProps) {
+  return <Form method="post">...</Form>;
+}
+```
+
+```tsx filename=routes/login.test.tsx
+import LoginRoute from "./login";
+
+test("LoginRoute renders error messages", async () => {
+  const Stub = createRoutesStub([
+    {
+      path: "/login",
+      Component: LoginRoute,
+      // ^ ❌ Types of property 'matches' are incompatible.
+      action() {
+        /*...*/
+      },
+    },
+  ]);
+
+  // ...
+});
+```
+
+These type errors are generally accurate if you try to setup your tests like this. As long as your stubbed `loader`/`action` functions match your real implementations, then the types for `loaderData`/`actionData` will be correct, but if they differ your types will be lying to you.
+
+`matches` is more complicated since you don't usually stub out all of the ancestor routes. In this example, there is no `root` route so `matches` will only contain your test route, while it will contain the root route and any other ancestors at runtime. There's no great way to automatically align the typegen types with the runtime types in your test.
+
+Therefore, if you need to test Route level components, we recommend you do that via an Integration/E2E test (Playwright, Cypress, etc.) against a running application because you're venturing out of unit testing territory when testing your route as a whole.
+
+If you _need_ to write a unit test against the route, you can add a `@ts-expect-error` comment in your test to silence the TypeScript error:
+
+```tsx
+const Stub = createRoutesStub([
+  {
+    path: "/login",
+    // @ts-expect-error: `matches` won't align between test code and app code
+    Component: LoginRoute,
+    action() {
+      /*...*/
+    },
+  },
+]);
+```

package/docs/start/index.md

@@ -0,0 +1,4 @@
+---
+title: Getting Started
+order: 1
+---

package/docs/start/modes.md

@@ -0,0 +1,201 @@
+---
+title: Picking a Mode
+order: 1
+---
+
+# Picking a Mode
+
+React Router is a multi-strategy router for React. There are three primary ways, or "modes", to use it in your app. Across the docs you'll see these icons indicating which mode the content is relevant to:
+
+[MODES: framework, data, declarative]
+
+<p></p>
+
+The features available in each mode are additive, so moving from Declarative to Data to Framework simply adds more features at the cost of architectural control. So pick your mode based on how much control or how much help you want from React Router.
+
+The mode depends on which "top level" router API you're using:
+
+## Declarative
+
+Declarative mode enables basic routing features like matching URLs to components, navigating around the app, and providing active states with APIs like `<Link>`, `useNavigate`, and `useLocation`.
+
+```tsx
+import { BrowserRouter } from "react-router";
+
+ReactDOM.createRoot(root).render(
+  <BrowserRouter>
+    <App />
+  </BrowserRouter>,
+);
+```
+
+## Data
+
+By moving route configuration outside of React rendering, Data Mode adds data loading, actions, pending states and more with APIs like `loader`, `action`, and `useFetcher`.
+
+```tsx
+import {
+  createBrowserRouter,
+  RouterProvider,
+} from "react-router";
+
+let router = createBrowserRouter([
+  {
+    path: "/",
+    Component: Root,
+    loader: loadRootData,
+  },
+]);
+
+ReactDOM.createRoot(root).render(
+  <RouterProvider router={router} />,
+);
+```
+
+## Framework
+
+Framework Mode wraps Data Mode with a Vite plugin to add the full React Router experience with:
+
+- type-safe `href`
+- type-safe Route Module API
+- intelligent code splitting
+- SPA, SSR, and static rendering strategies
+- and more
+
+```ts filename=routes.ts
+import { index, route } from "@react-router/dev/routes";
+
+export default [
+  index("./home.tsx"),
+  route("products/:pid", "./product.tsx"),
+];
+```
+
+You'll then have access to the Route Module API with type-safe params, loaderData, code splitting, SPA/SSR/SSG strategies, and more.
+
+```ts filename=product.tsx
+import { Route } from "./+types/product.tsx";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  let product = await getProduct(params.pid);
+  return { product };
+}
+
+export default function Product({
+  loaderData,
+}: Route.ComponentProps) {
+  return <div>{loaderData.product.name}</div>;
+}
+```
+
+## Decision Advice
+
+Every mode supports any architecture and deployment target, so the question isn't really about if you want SSR, SPA, etc. It's about how much you want to do yourself.
+
+**Use Framework Mode if you:**
+
+- are too new to have an opinion
+- are considering Next.js, Solid Start, SvelteKit, Astro, TanStack Start, etc. and want to compare
+- just want to build something with React
+- might want to server render, might not
+- are coming from Remix (React Router v7 is the "next version" after Remix v2)
+- are migrating from Next.js
+
+[→ Get Started with Framework Mode](./framework/installation).
+
+**Use Data Mode if you:**
+
+- want data features but also want to have control over bundling, data, and server abstractions
+- started a data router in v6.4 and are happy with it
+
+[→ Get Started with Data Mode](./data/custom).
+
+**Use Declarative Mode if you:**
+
+- want to use React Router as simply as possible
+- are coming from v6 and are happy with the `<BrowserRouter>`
+- have a data layer that either skips pending states (like local first, background data replication/sync) or has its own abstractions for them
+- are coming from Create React App (you may want to consider framework mode though)
+
+[→ Get Started with Declarative Mode](./declarative/installation).
+
+## API + Mode Availability Table
+
+This is mostly for the LLMs, but knock yourself out:
+
+| API                            | Framework | Data | Declarative |
+| ------------------------------ | --------- | ---- | ----------- |
+| Await                          | ✅        | ✅   |             |
+| Form                           | ✅        | ✅   |
+| Link                           | ✅        | ✅   | ✅          |
+| `<Link discover>`              | ✅        |      |             |
+| `<Link prefetch>`              | ✅        |      |             |
+| `<Link preventScrollReset>`    | ✅        | ✅   |             |
+| Links                          | ✅        |      |             |
+| Meta                           | ✅        |      |             |
+| NavLink                        | ✅        | ✅   | ✅          |
+| `<NavLink discover>`           | ✅        |      |             |
+| `<NavLink prefetch>`           | ✅        |      |             |
+| `<NavLink preventScrollReset>` | ✅        | ✅   |             |
+| NavLink `isPending`            | ✅        | ✅   |             |
+| Navigate                       | ✅        | ✅   | ✅          |
+| Outlet                         | ✅        | ✅   | ✅          |
+| PrefetchPageLinks              | ✅        |      |             |
+| Route                          | ✅        | ✅   | ✅          |
+| Routes                         | ✅        | ✅   | ✅          |
+| Scripts                        | ✅        |      |             |
+| ScrollRestoration              | ✅        | ✅   |             |
+| ServerRouter                   | ✅        |      |             |
+| usePrompt                      | ✅        | ✅   |             |
+| useActionData                  | ✅        | ✅   |             |
+| useAsyncError                  | ✅        | ✅   |             |
+| useAsyncValue                  | ✅        | ✅   |             |
+| useBeforeUnload                | ✅        | ✅   | ✅          |
+| useBlocker                     | ✅        | ✅   |             |
+| useFetcher                     | ✅        | ✅   |             |
+| useFetchers                    | ✅        | ✅   |             |
+| useFormAction                  | ✅        | ✅   |             |
+| useHref                        | ✅        | ✅   | ✅          |
+| useInRouterContext             | ✅        | ✅   | ✅          |
+| useLinkClickHandler            | ✅        | ✅   | ✅          |
+| useLoaderData                  | ✅        | ✅   |             |
+| useLocation                    | ✅        | ✅   | ✅          |
+| useMatch                       | ✅        | ✅   | ✅          |
+| useMatches                     | ✅        | ✅   |             |
+| useNavigate                    | ✅        | ✅   | ✅          |
+| useNavigation                  | ✅        | ✅   |             |
+| useNavigationType              | ✅        | ✅   | ✅          |
+| useOutlet                      | ✅        | ✅   | ✅          |
+| useOutletContext               | ✅        | ✅   | ✅          |
+| useParams                      | ✅        | ✅   | ✅          |
+| useResolvedPath                | ✅        | ✅   | ✅          |
+| useRevalidator                 | ✅        | ✅   |             |
+| useRouteError                  | ✅        | ✅   |             |
+| useRouteLoaderData             | ✅        | ✅   |             |
+| useRoutes                      | ✅        | ✅   | ✅          |
+| useSearchParams                | ✅        | ✅   | ✅          |
+| useSubmit                      | ✅        | ✅   |             |
+| useViewTransitionState         | ✅        | ✅   |             |
+| isCookieFunction               | ✅        | ✅   |             |
+| isSessionFunction              | ✅        | ✅   |             |
+| createCookie                   | ✅        | ✅   |             |
+| createCookieSessionStorage     | ✅        | ✅   |             |
+| createMemorySessionStorage     | ✅        | ✅   |             |
+| createPath                     | ✅        | ✅   | ✅          |
+| createRoutesFromElements       |           | ✅   |             |
+| createRoutesStub               | ✅        | ✅   |             |
+| createSearchParams             | ✅        | ✅   | ✅          |
+| data                           | ✅        | ✅   |             |
+| generatePath                   | ✅        | ✅   | ✅          |
+| href                           | ✅        |      |             |
+| isCookie                       | ✅        | ✅   |             |
+| isRouteErrorResponse           | ✅        | ✅   |             |
+| isSession                      | ✅        | ✅   |             |
+| matchPath                      | ✅        | ✅   | ✅          |
+| matchRoutes                    | ✅        | ✅   | ✅          |
+| parsePath                      | ✅        | ✅   | ✅          |
+| redirect                       | ✅        | ✅   |             |
+| redirectDocument               | ✅        | ✅   |             |
+| renderMatches                  | ✅        | ✅   | ✅          |
+| replace                        | ✅        | ✅   |             |
+| resolvePath                    | ✅        | ✅   | ✅          |