react-router 7.16.0 → 7.17.0

package/docs/start/data/custom.md

@@ -0,0 +1,198 @@
+---
+title: Custom Framework
+order: 8
+---
+
+# Custom Framework
+
+[MODES: data]
+
+## Introduction
+
+Instead of using `@react-router/dev`, you can integrate React Router's framework features (like loaders, actions, fetchers, etc.) into your own bundler and server abstractions with Data Mode.
+
+## Client Rendering
+
+### 1. Create a Router
+
+The browser runtime API that enables route module APIs (loaders, actions, etc.) is `createBrowserRouter`.
+
+It takes an array of route objects that support loaders, actions, error boundaries and more. The React Router Vite plugin creates one of these from `routes.ts`, but you can create one manually (or with an abstraction) and use your own bundler.
+
+```tsx
+import { createBrowserRouter } from "react-router";
+
+let router = createBrowserRouter([
+  {
+    path: "/",
+    Component: Root,
+    children: [
+      {
+        path: "shows/:showId",
+        Component: Show,
+        loader: ({ request, params }) =>
+          fetch(`/api/show/${params.showId}.json`, {
+            signal: request.signal,
+          }),
+      },
+    ],
+  },
+]);
+```
+
+### 2. Render the Router
+
+To render the router in the browser, use `<RouterProvider>`.
+
+```tsx
+import {
+  createBrowserRouter,
+  RouterProvider,
+} from "react-router";
+import { createRoot } from "react-dom/client";
+
+createRoot(document.getElementById("root")).render(
+  <RouterProvider router={router} />,
+);
+```
+
+### 3. Lazy Loading
+
+Routes can take most of their definition lazily with the `lazy` property.
+
+```tsx
+createBrowserRouter([
+  {
+    path: "/show/:showId",
+    lazy: {
+      loader: async () =>
+        (await import("./show.loader.js")).loader,
+      action: async () =>
+        (await import("./show.action.js")).action,
+      Component: async () =>
+        (await import("./show.component.js")).Component,
+    },
+  },
+]);
+```
+
+## Server Rendering
+
+To server render a custom setup, there are a few server APIs available for rendering and data loading.
+
+This guide simply gives you some ideas about how it works. For deeper understanding, please see the [Custom Framework Example Repo](https://github.com/remix-run/custom-react-router-framework-example)
+
+### 1. Define Your Routes
+
+Routes are the same kinds of objects on the server as the client.
+
+```tsx
+export default [
+  {
+    path: "/",
+    Component: Root,
+    children: [
+      {
+        path: "shows/:showId",
+        Component: Show,
+        loader: ({ params }) => {
+          return db.loadShow(params.id);
+        },
+      },
+    ],
+  },
+];
+```
+
+### 2. Create a static handler
+
+Turn your routes into a request handler with `createStaticHandler`:
+
+```tsx
+import { createStaticHandler } from "react-router";
+import routes from "./some-routes";
+
+let { query, dataRoutes } = createStaticHandler(routes);
+```
+
+### 3. Get Routing Context and Render
+
+React Router works with web fetch [Requests](https://developer.mozilla.org/en-US/docs/Web/API/Request), so if your server doesn't, you'll need to adapt whatever objects it uses to a web fetch `Request` object.
+
+This step assumes your server receives `Request` objects.
+
+```tsx
+import { renderToString } from "react-dom/server";
+import {
+  createStaticHandler,
+  createStaticRouter,
+  StaticRouterProvider,
+} from "react-router";
+
+import routes from "./some-routes.js";
+
+let { query, dataRoutes } = createStaticHandler(routes);
+
+export async function handler(request: Request) {
+  // 1. run actions/loaders to get the routing context with `query`
+  let context = await query(request);
+
+  // If `query` returns a Response, send it raw (a route probably a redirected)
+  if (context instanceof Response) {
+    return context;
+  }
+
+  // 2. Create a static router for SSR
+  let router = createStaticRouter(dataRoutes, context);
+
+  // 3. Render everything with StaticRouterProvider
+  let html = renderToString(
+    <StaticRouterProvider
+      router={router}
+      context={context}
+    />,
+  );
+
+  // Setup headers from action and loaders from deepest match
+  let leaf = context.matches[context.matches.length - 1];
+  let actionHeaders = context.actionHeaders[leaf.route.id];
+  let loaderHeaders = context.loaderHeaders[leaf.route.id];
+  let headers = new Headers(actionHeaders);
+  if (loaderHeaders) {
+    for (let [key, value] of loaderHeaders.entries()) {
+      headers.append(key, value);
+    }
+  }
+
+  headers.set("Content-Type", "text/html; charset=utf-8");
+
+  // 4. send a response
+  return new Response(`<!DOCTYPE html>${html}`, {
+    status: context.statusCode,
+    headers,
+  });
+}
+```
+
+### 4. Hydrate in the browser
+
+Hydration data is embedded onto `window.__staticRouterHydrationData`, use that to initialize your client side router and render a `<RouterProvider>`.
+
+```tsx
+import { StrictMode } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { RouterProvider } from "react-router/dom";
+import routes from "./app/routes.js";
+import { createBrowserRouter } from "react-router";
+
+let router = createBrowserRouter(routes, {
+  hydrationData: window.__staticRouterHydrationData,
+});
+
+hydrateRoot(
+  document,
+  <StrictMode>
+    <RouterProvider router={router} />
+  </StrictMode>,
+);
+```

package/docs/start/data/data-loading.md

@@ -0,0 +1,44 @@
+---
+title: Data Loading
+order: 4
+---
+
+# Data Loading
+
+[MODES: data]
+
+## Providing Data
+
+Data is provided to route components from route loaders:
+
+```tsx
+createBrowserRouter([
+  {
+    path: "/",
+    loader: async () => {
+      // return data from here
+      return { records: await getSomeRecords() };
+    },
+    Component: MyRoute,
+  },
+]);
+```
+
+## Accessing Data
+
+The data is available in route components with `useLoaderData`.
+
+```tsx
+import { useLoaderData } from "react-router";
+
+function MyRoute() {
+  const { records } = useLoaderData();
+  return <div>{records.length}</div>;
+}
+```
+
+As the user navigates between routes, the loaders are called before the route component is rendered.
+
+---
+
+Next: [Actions](./actions)

package/docs/start/data/index.md

@@ -0,0 +1,4 @@
+---
+title: Data Mode
+order: 3
+---

package/docs/start/data/installation.md

@@ -0,0 +1,52 @@
+---
+title: Installation
+order: 1
+---
+
+# Installation
+
+[MODES: data]
+
+## Bootstrap with a Bundler Template
+
+You can start with a React template from Vite and choose "React", otherwise bootstrap your application however you prefer (Parcel, Webpack, etc).
+
+```shellscript nonumber
+npx create-vite@latest
+```
+
+## Install React Router
+
+Next install React Router from npm:
+
+```shellscript nonumber
+npm i react-router
+```
+
+## Create a Router and Render
+
+Create a router and pass it to `RouterProvider`:
+
+```tsx lines=[3-4,6-11,16]
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { createBrowserRouter } from "react-router";
+import { RouterProvider } from "react-router/dom";
+
+const router = createBrowserRouter([
+  {
+    path: "/",
+    element: <div>Hello World</div>,
+  },
+]);
+
+const root = document.getElementById("root");
+
+ReactDOM.createRoot(root).render(
+  <RouterProvider router={router} />,
+);
+```
+
+---
+
+Next: [Routing](./routing)

package/docs/start/data/navigating.md

@@ -0,0 +1,12 @@
+---
+title: Navigating
+order: 6
+---
+
+# Navigating
+
+Navigating in Data Mode is the same as Framework Mode, please see the [Navigating](../framework/navigating) guide for more information.
+
+---
+
+Next: [Pending UI](./pending-ui)

package/docs/start/data/pending-ui.md

@@ -0,0 +1,12 @@
+---
+title: Pending UI
+order: 7
+---
+
+# Pending UI
+
+Pending UI is the same as Framework Mode, please see the [Pending UI](../framework/pending-ui) guide for more information.
+
+---
+
+Next: [Custom Framework](./custom)

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

@@ -0,0 +1,268 @@
+---
+title: Route Object
+order: 3
+---
+
+# Route Object
+
+[MODES: data]
+
+## Introduction
+
+The objects passed to `createBrowserRouter` are called Route Objects.
+
+```tsx lines=[2-5]
+createBrowserRouter([
+  {
+    path: "/",
+    Component: App,
+  },
+]);
+```
+
+Route modules are the foundation of React Router's data features, they define:
+
+- data loading
+- actions
+- revalidation
+- error boundaries
+- and more
+
+This guide is a quick overview of every route object feature.
+
+## Component
+
+The `Component` property in a route object defines the component that will render when the route matches.
+
+```tsx lines=[4]
+createBrowserRouter([
+  {
+    path: "/",
+    Component: MyRouteComponent,
+  },
+]);
+
+function MyRouteComponent() {
+  return (
+    <div>
+      <h1>Look ma!</h1>
+      <p>
+        I'm still using React Router after like 10 years.
+      </p>
+    </div>
+  );
+}
+```
+
+## `middleware`
+
+Route [middleware][middleware] runs sequentially before and after navigations. This gives you a singular place to do things like logging and authentication. The `next` function continues down the chain, and on the leaf route the `next` function executes the loaders/actions for the navigation.
+
+```tsx
+createBrowserRouter([
+  {
+    path: "/",
+    middleware: [loggingMiddleware],
+    loader: rootLoader,
+    Component: Root,
+    children: [{
+      path: 'auth',
+      middleware: [authMiddleware],
+      loader: authLoader,
+      Component: Auth,
+      children: [...]
+    }]
+  },
+]);
+
+async function loggingMiddleware({ request }, next) {
+  let url = new URL(request.url);
+  console.log(`Starting navigation: ${url.pathname}${url.search}`);
+  const start = performance.now();
+  await next();
+  const duration = performance.now() - start;
+  console.log(`Navigation completed in ${duration}ms`);
+}
+
+const userContext = createContext<User>();
+
+async function authMiddleware ({ context }) {
+  const userId = getUserId();
+
+  if (!userId) {
+    throw redirect("/login");
+  }
+
+  context.set(userContext, await getUserById(userId));
+};
+```
+
+See also:
+
+- [Middleware][middleware]
+
+## `loader`
+
+Route loaders provide data to route components before they are rendered.
+
+```tsx
+import {
+  useLoaderData,
+  createBrowserRouter,
+} from "react-router";
+
+createBrowserRouter([
+  {
+    path: "/",
+    loader: loader,
+    Component: MyRoute,
+  },
+]);
+
+async function loader({ params }) {
+  return { message: "Hello, world!" };
+}
+
+function MyRoute() {
+  let data = useLoaderData();
+  return <h1>{data.message}</h1>;
+}
+```
+
+See also:
+
+- [`loader` params][loader-params]
+
+## `action`
+
+Route actions allow server-side data mutations with automatic revalidation of all loader data on the page when called from `<Form>`, `useFetcher`, and `useSubmit`.
+
+```tsx
+import {
+  createBrowserRouter,
+  useLoaderData,
+  useActionData,
+  Form,
+} from "react-router";
+import { TodoList } from "~/components/TodoList";
+
+createBrowserRouter([
+  {
+    path: "/items",
+    action: action,
+    loader: loader,
+    Component: Items,
+  },
+]);
+
+async function action({ request }) {
+  const data = await request.formData();
+  const todo = await fakeDb.addItem({
+    title: data.get("title"),
+  });
+  return { ok: true };
+}
+
+// this data will be revalidated after the action completes...
+async function loader() {
+  const items = await fakeDb.getItems();
+  return { items };
+}
+
+// ...so that the list here is updated automatically
+export default function Items() {
+  let data = useLoaderData();
+  return (
+    <div>
+      <List items={data.items} />
+      <Form method="post" navigate={false}>
+        <input type="text" name="title" />
+        <button type="submit">Create Todo</button>
+      </Form>
+    </div>
+  );
+}
+```
+
+## `shouldRevalidate`
+
+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.
+
+A route loader is revalidated when:
+
+- its own route params change
+- any change to URL search params
+- after an action is called and returns a non-error status code
+
+By defining this function, you opt out of the default behavior completely and can manually control when loader data is revalidated for navigations and form submissions.
+
+```tsx
+import type { ShouldRevalidateFunctionArgs } from "react-router";
+
+function shouldRevalidate(
+  arg: ShouldRevalidateFunctionArgs,
+) {
+  return true; // false
+}
+
+createBrowserRouter([
+  {
+    path: "/",
+    shouldRevalidate: shouldRevalidate,
+    Component: MyRoute,
+  },
+]);
+```
+
+[`ShouldRevalidateFunctionArgs` Reference Documentation ↗](https://api.reactrouter.com/v7/interfaces/react-router.ShouldRevalidateFunctionArgs.html)
+
+Please note the default behavior is different in [Framework Mode](../modes).
+
+## `lazy`
+
+Most properties can be lazily imported to reduce the initial bundle size.
+
+```tsx
+createBrowserRouter([
+  {
+    path: "/app",
+    lazy: async () => {
+      // load component and loader in parallel before rendering
+      const [Component, loader] = await Promise.all([
+        import("./app"),
+        import("./app-loader"),
+      ]);
+      return { Component, loader };
+    },
+  },
+]);
+```
+
+## `handle`
+
+Route handle allows apps to add anything to a route match in `useMatches` to create abstractions (like breadcrumbs, etc.).
+
+```tsx
+createBrowserRouter([
+  {
+    path: "/app",
+    handle: {
+      breadcrumb: "App",
+    },
+  },
+]);
+```
+
+See also:
+
+- [`useMatches`][use-matches]
+
+---
+
+Next: [Data Loading](./data-loading)
+
+[loader-params]: https://api.reactrouter.com/v7/interfaces/react-router.LoaderFunctionArgs
+[middleware]: ../../how-to/middleware
+[use-matches]: ../../api/hooks/useMatches