react-router 7.16.0 → 7.17.0

package/docs/how-to/error-boundary.md

@@ -0,0 +1,231 @@
+---
+title: Error Boundaries
+---
+
+# Error Boundaries
+
+[MODES: framework, data]
+
+<br/>
+<br/>
+
+To avoid rendering an empty page to users, route modules will automatically catch errors in your code and render the closest `ErrorBoundary`.
+
+Error boundaries are not intended for rendering form validation errors or error reporting. Please see [Form Validation](./form-validation) and [Error Reporting](./error-reporting) instead.
+
+## 1. Add a root error boundary
+
+All applications should at a minimum export a root error boundary. This one handles the three main cases:
+
+- Thrown `data` with a status code and text
+- Instances of errors with a stack trace
+- Randomly thrown values
+
+### Framework Mode
+
+[modes: framework]
+
+In [Framework Mode][picking-a-mode], errors are passed to the route-level error boundary as a prop (see [`Route.ErrorBoundaryProps`][type-safety]), so you don't need to use a hook to grab it:
+
+```tsx filename=root.tsx lines=[1,3-5]
+import { Route } from "./+types/root";
+
+export function ErrorBoundary({
+  error,
+}: Route.ErrorBoundaryProps) {
+  if (isRouteErrorResponse(error)) {
+    return (
+      <>
+        <h1>
+          {error.status} {error.statusText}
+        </h1>
+        <p>{error.data}</p>
+      </>
+    );
+  } else if (error instanceof Error) {
+    return (
+      <div>
+        <h1>Error</h1>
+        <p>{error.message}</p>
+        <p>The stack trace is:</p>
+        <pre>{error.stack}</pre>
+      </div>
+    );
+  } else {
+    return <h1>Unknown Error</h1>;
+  }
+}
+```
+
+### Data Mode
+
+[modes: data]
+
+In [Data Mode][picking-a-mode], the `ErrorBoundary` doesn't receive props, so you can access it via `useRouteError`:
+
+```tsx lines=[1,6,16]
+import { useRouteError } from "react-router";
+
+let router = createBrowserRouter([
+  {
+    path: "/",
+    ErrorBoundary: RootErrorBoundary,
+    Component: Root,
+  },
+]);
+
+function Root() {
+  /* ... */
+}
+
+function RootErrorBoundary() {
+  let error = useRouteError();
+  if (isRouteErrorResponse(error)) {
+    return (
+      <>
+        <h1>
+          {error.status} {error.statusText}
+        </h1>
+        <p>{error.data}</p>
+      </>
+    );
+  } else if (error instanceof Error) {
+    return (
+      <div>
+        <h1>Error</h1>
+        <p>{error.message}</p>
+        <p>The stack trace is:</p>
+        <pre>{error.stack}</pre>
+      </div>
+    );
+  } else {
+    return <h1>Unknown Error</h1>;
+  }
+}
+```
+
+## 2. Write a bug
+
+[modes: framework,data]
+
+It's not recommended to intentionally throw errors to force the error boundary to render as a means of control flow. Error Boundaries are primarily for catching unintentional errors in your code.
+
+```tsx
+export async function loader() {
+  return undefined();
+}
+```
+
+This will render the `instanceof Error` branch of the UI from step 1.
+
+This is not just for loaders, but for all route module APIs: loaders, actions, components, headers, links, and meta.
+
+## 3. Throw data in loaders/actions
+
+[modes: framework,data]
+
+There are exceptions to the rule in #2, especially 404s. You can intentionally `throw data()` (with a proper status code) to the closest error boundary when your loader can't find what it needs to render the page. Throw a 404 and move on.
+
+```tsx
+import { data } from "react-router";
+
+export async function loader({ params }) {
+  let record = await fakeDb.getRecord(params.id);
+  if (!record) {
+    throw data("Record Not Found", { status: 404 });
+  }
+  return record;
+}
+```
+
+This will render the `isRouteErrorResponse` branch of the UI from step 1.
+
+## 4. Nested error boundaries
+
+When an error is thrown, the "closest error boundary" will be rendered.
+
+### Framework Mode
+
+[modes: framework]
+
+Consider these nested routes:
+
+```tsx filename="routes.ts"
+// ✅ has error boundary
+route("/app", "app.tsx", [
+  // ❌ no error boundary
+  route("invoices", "invoices.tsx", [
+    // ✅ has error boundary
+    route("invoices/:id", "invoice-page.tsx", [
+      // ❌ no error boundary
+      route("payments", "payments.tsx"),
+    ]),
+  ]),
+]);
+```
+
+The following table shows which error boundary will render given the origin of the error:
+
+| error origin     | rendered boundary |
+| ---------------- | ----------------- |
+| app.tsx          | app.tsx           |
+| invoices.tsx     | app.tsx           |
+| invoice-page.tsx | invoice-page.tsx  |
+| payments.tsx     | invoice-page.tsx  |
+
+### Data Mode
+
+[modes: data]
+
+In Data Mode, the equivalent route tree might look like:
+
+```tsx
+let router = createBrowserRouter([
+  {
+    path: "/app",
+    Component: App,
+    ErrorBoundary: AppErrorBoundary, // ✅ has error boundary
+    children: [
+      {
+        path: "invoices",
+        Component: Invoices, // ❌ no error boundary
+        children: [
+          {
+            path: ":id",
+            Component: Invoice,
+            ErrorBoundary: InvoiceErrorBoundary, // ✅ has error boundary
+            children: [
+              {
+                path: "payments",
+                Component: Payments, // ❌ no error boundary
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+]);
+```
+
+The following table shows which error boundary will render given the origin of the error:
+
+| error origin | rendered boundary      |
+| ------------ | ---------------------- |
+| `App`        | `AppErrorBoundary`     |
+| `Invoices`   | `AppErrorBoundary`     |
+| `Invoice`    | `InvoiceErrorBoundary` |
+| `Payments`   | `InvoiceErrorBoundary` |
+
+## Error Sanitization
+
+[modes: framework]
+
+In Framework Mode when building for production, any errors that happen on the server are automatically sanitized before being sent to the browser to prevent leaking any sensitive server information (like stack traces).
+
+This means that a thrown `Error` will have a generic message and no stack trace in production in the browser. The original error is untouched on the server.
+
+Also note that data sent with `throw data(yourData)` is not sanitized as the data there is intended to be rendered.
+
+[picking-a-mode]: ../start/modes
+[type-safety]: ../explanation/type-safety

package/docs/how-to/error-reporting.md

@@ -0,0 +1,142 @@
+---
+title: Error Reporting
+---
+
+# Error Reporting
+
+[MODES: framework,data]
+
+<br/>
+<br/>
+
+React Router catches errors in your route modules and sends them to [error boundaries](./error-boundary) to prevent blank pages when errors occur. However, `ErrorBoundary` isn't sufficient for logging and reporting errors.
+
+## Server Errors
+
+[modes: framework]
+
+To access these caught errors on the server, use the `handleError` export of the server entry module.
+
+### 1. Reveal the server entry
+
+If you don't see [`entry.server.tsx`][entryserver] in your app directory, you're using a default entry. Reveal it with this cli command:
+
+```shellscript nonumber
+react-router reveal entry.server
+```
+
+### 2. Export your error handler
+
+This function is called whenever React Router catches an error in your application on the server.
+
+```tsx filename=entry.server.tsx
+import { type HandleErrorFunction } from "react-router";
+
+export const handleError: HandleErrorFunction = (
+  error,
+  { request },
+) => {
+  // React Router may abort some interrupted requests, don't log those
+  if (!request.signal.aborted) {
+    myReportError(error);
+
+    // make sure to still log the error so you can see it
+    console.error(error);
+  }
+};
+```
+
+See also:
+
+- [`handleError`][handleError]
+
+## Client Errors
+
+To access these caught errors on the client, use the `onError` prop on your [`HydratedRouter`][hydratedrouter] or [`RouterProvider`][routerprovider] component.
+
+### Framework Mode
+
+[modes: framework]
+
+#### 1. Reveal the client entry
+
+If you don't see [`entry.client.tsx`][entryclient] in your app directory, you're using a default entry. Reveal it with this cli command:
+
+```shellscript nonumber
+react-router reveal entry.client
+```
+
+#### 2. Add your error handler
+
+This function is called whenever React Router catches an error in your application on the client.
+
+```tsx filename=entry.client.tsx
+import { type ClientOnErrorFunction } from "react-router";
+
+const onError: ClientOnErrorFunction = (
+  error,
+  { location, params, pattern, errorInfo },
+) => {
+  myReportError(error, location, errorInfo);
+
+  // make sure to still log the error so you can see it
+  console.error(error, errorInfo);
+};
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    <StrictMode>
+      <HydratedRouter onError={onError} />
+    </StrictMode>,
+  );
+});
+```
+
+See also:
+
+- [`<HydratedRouter onError>`][hydratedrouter-onerror]
+
+### Data Mode
+
+[modes: data]
+
+This function is called whenever React Router catches an error in your application on the client.
+
+```tsx
+import {
+  createBrowserRouter,
+  type ClientOnErrorFunction,
+} from "react-router";
+import { RouterProvider } from "react-router/dom";
+
+const onError: ClientOnErrorFunction = (
+  error,
+  { location, params, pattern, errorInfo },
+) => {
+  myReportError(error, location, errorInfo);
+
+  // make sure to still log the error so you can see it
+  console.error(error, errorInfo);
+};
+
+const router = createBrowserRouter(routes);
+
+function App() {
+  return (
+    <RouterProvider router={router} onError={onError} />
+  );
+}
+```
+
+See also:
+
+- [`<RouterProvider onError>`][routerprovider-onerror]
+
+[entryserver]: ../api/framework-conventions/entry.server.tsx
+[handleError]: ../api/framework-conventions/entry.server.tsx#handleerror
+[entryclient]: ../api/framework-conventions/entry.client.tsx
+[hydratedrouter]: ../api/framework-routers/HydratedRouter
+[routerprovider]: ../api/data-routers/RouterProvider
+[hydratedrouter-onerror]: ../api/framework-routers/HydratedRouter#onError
+[routerprovider-onerror]: ../api/data-routers/RouterProvider#onError

package/docs/how-to/fetchers.md

@@ -0,0 +1,307 @@
+---
+title: Using Fetchers
+---
+
+# Using Fetchers
+
+[MODES: framework, data]
+
+<br/>
+<br/>
+
+Fetchers are useful for creating complex, dynamic user interfaces that require multiple, concurrent data interactions without causing a navigation.
+
+Fetchers track their own, independent state and can be used to load data, mutate data, submit forms, and generally interact with loaders and actions.
+
+## Calling Actions
+
+The most common case for a fetcher is to submit data to an action, triggering a revalidation of route data. Consider the following route module:
+
+```tsx
+import { useLoaderData } from "react-router";
+
+export async function clientLoader({ request }) {
+  let title = localStorage.getItem("title") || "No Title";
+  return { title };
+}
+
+export default function Component() {
+  let data = useLoaderData();
+  return (
+    <div>
+      <h1>{data.title}</h1>
+    </div>
+  );
+}
+```
+
+### 1. Add an action
+
+First we'll add an action to the route for the fetcher to call:
+
+```tsx lines=[7-11]
+import { useLoaderData } from "react-router";
+
+export async function clientLoader({ request }) {
+  // ...
+}
+
+export async function clientAction({ request }) {
+  await new Promise((res) => setTimeout(res, 1000));
+  let data = await request.formData();
+  localStorage.setItem("title", data.get("title"));
+  return { ok: true };
+}
+
+export default function Component() {
+  let data = useLoaderData();
+  // ...
+}
+```
+
+### 2. Create a fetcher
+
+Next create a fetcher and render a form with it:
+
+```tsx lines=[7,12-14]
+import { useLoaderData, useFetcher } from "react-router";
+
+// ...
+
+export default function Component() {
+  let data = useLoaderData();
+  let fetcher = useFetcher();
+  return (
+    <div>
+      <h1>{data.title}</h1>
+
+      <fetcher.Form method="post">
+        <input type="text" name="title" />
+      </fetcher.Form>
+    </div>
+  );
+}
+```
+
+### 3. Submit the form
+
+If you submit the form now, the fetcher will call the action and revalidate the route data automatically.
+
+### 4. Render pending state
+
+Fetchers make their state available during the async work so you can render pending UI the moment the user interacts:
+
+```tsx lines=[10]
+export default function Component() {
+  let data = useLoaderData();
+  let fetcher = useFetcher();
+  return (
+    <div>
+      <h1>{data.title}</h1>
+
+      <fetcher.Form method="post">
+        <input type="text" name="title" />
+        {fetcher.state !== "idle" && <p>Saving...</p>}
+      </fetcher.Form>
+    </div>
+  );
+}
+```
+
+### 5. Optimistic UI
+
+Sometimes there's enough information in the form to render the next state immediately. You can access the form data with `fetcher.formData`:
+
+```tsx lines=[3-4,8]
+export default function Component() {
+  let data = useLoaderData();
+  let fetcher = useFetcher();
+  let title = fetcher.formData?.get("title") || data.title;
+
+  return (
+    <div>
+      <h1>{title}</h1>
+
+      <fetcher.Form method="post">
+        <input type="text" name="title" />
+        {fetcher.state !== "idle" && <p>Saving...</p>}
+      </fetcher.Form>
+    </div>
+  );
+}
+```
+
+### 6. Fetcher Data and Validation
+
+Data returned from an action is available in the fetcher's `data` property. This is primarily useful for returning error messages to the user for a failed mutation:
+
+```tsx lines=[7-10,28-32]
+// ...
+
+export async function clientAction({ request }) {
+  await new Promise((res) => setTimeout(res, 1000));
+  let data = await request.formData();
+
+  let title = data.get("title") as string;
+  if (title.trim() === "") {
+    return { ok: false, error: "Title cannot be empty" };
+  }
+
+  localStorage.setItem("title", title);
+  return { ok: true, error: null };
+}
+
+export default function Component() {
+  let data = useLoaderData();
+  let fetcher = useFetcher();
+  let title = fetcher.formData?.get("title") || data.title;
+
+  return (
+    <div>
+      <h1>{title}</h1>
+
+      <fetcher.Form method="post">
+        <input type="text" name="title" />
+        {fetcher.state !== "idle" && <p>Saving...</p>}
+        {fetcher.data?.error && (
+          <p style={{ color: "red" }}>
+            {fetcher.data.error}
+          </p>
+        )}
+      </fetcher.Form>
+    </div>
+  );
+}
+```
+
+## Loading Data
+
+Another common use case for fetchers is to load data from a route for something like a combobox.
+
+### 1. Create a search route
+
+Consider the following route with a very basic search:
+
+```tsx filename=./search-users.tsx
+// { path: '/search-users', filename: './search-users.tsx' }
+const users = [
+  { id: 1, name: "Ryan" },
+  { id: 2, name: "Michael" },
+  // ...
+];
+
+export async function loader({ request }) {
+  await new Promise((res) => setTimeout(res, 300));
+  let url = new URL(request.url);
+  let query = url.searchParams.get("q");
+  return users.filter((user) =>
+    user.name.toLowerCase().includes(query.toLowerCase()),
+  );
+}
+```
+
+### 2. Render a fetcher in a combobox component
+
+```tsx
+import { useFetcher } from "react-router";
+
+export function UserSearchCombobox() {
+  let fetcher = useFetcher();
+  return (
+    <div>
+      <fetcher.Form method="get" action="/search-users">
+        <input type="text" name="q" />
+      </fetcher.Form>
+    </div>
+  );
+}
+```
+
+- The action points to the route we created above: "/search-users"
+- The name of the input is "q" to match the query parameter
+
+### 3. Add type inference
+
+```tsx lines=[2,5]
+import { useFetcher } from "react-router";
+import type { loader } from "./search-users";
+
+export function UserSearchCombobox() {
+  let fetcher = useFetcher<typeof loader>();
+  // ...
+}
+```
+
+Ensure you use `import type` so you only import the types.
+
+### 4. Render the data
+
+```tsx lines=[10-16]
+import { useFetcher } from "react-router";
+
+export function UserSearchCombobox() {
+  let fetcher = useFetcher<typeof loader>();
+  return (
+    <div>
+      <fetcher.Form method="get" action="/search-users">
+        <input type="text" name="q" />
+      </fetcher.Form>
+      {fetcher.data && (
+        <ul>
+          {fetcher.data.map((user) => (
+            <li key={user.id}>{user.name}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+Note you will need to hit "enter" to submit the form and see the results.
+
+### 5. Render a pending state
+
+```tsx lines=[12-14]
+import { useFetcher } from "react-router";
+
+export function UserSearchCombobox() {
+  let fetcher = useFetcher<typeof loader>();
+  return (
+    <div>
+      <fetcher.Form method="get" action="/search-users">
+        <input type="text" name="q" />
+      </fetcher.Form>
+      {fetcher.data && (
+        <ul
+          style={{
+            opacity: fetcher.state === "idle" ? 1 : 0.25,
+          }}
+        >
+          {fetcher.data.map((user) => (
+            <li key={user.id}>{user.name}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+```
+
+### 6. Search on user input
+
+Fetchers can be submitted programmatically with `fetcher.submit`:
+
+```tsx lines=[5-7]
+<fetcher.Form method="get" action="/search-users">
+  <input
+    type="text"
+    name="q"
+    onChange={(event) => {
+      fetcher.submit(event.currentTarget.form);
+    }}
+  />
+</fetcher.Form>
+```
+
+Note the input event's form is passed as the first argument to `fetcher.submit`. The fetcher will use that form to submit the request, reading its attributes and serializing the data from its elements.