react-router 7.15.1 → 8.0.0-pre.0

package/docs/how-to/resource-routes.md

@@ -0,0 +1,126 @@
+---
+title: Resource Routes
+---
+
+# Resource Routes
+
+[MODES: framework, data]
+
+<br/>
+<br/>
+
+When server rendering, routes can serve "resources" instead of rendering components, like images, PDFs, JSON payloads, webhooks, etc.
+
+## Defining a Resource Route
+
+A route becomes a resource route by convention when its module exports a loader or action but does not export a default component.
+
+Consider a route that serves a PDF instead of UI:
+
+```ts
+route("/reports/pdf/:id", "pdf-report.ts");
+```
+
+```tsx filename=pdf-report.ts
+import type { Route } from "./+types/pdf-report";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  const report = await getReport(params.id);
+  const pdf = await generateReportPDF(report);
+  return new Response(pdf, {
+    status: 200,
+    headers: {
+      "Content-Type": "application/pdf",
+    },
+  });
+}
+```
+
+Note there is no default export. That makes this route a resource route.
+
+## Linking to Resource Routes
+
+When linking to resource routes, use `<a>` or `<Link reloadDocument>`, otherwise React Router will attempt to use client side routing and fetching the payload (you'll get a helpful error message if you make this mistake).
+
+```tsx
+<Link reloadDocument to="/reports/pdf/123">
+  View as PDF
+</Link>
+```
+
+## Handling different request methods
+
+GET requests are handled by the `loader`, while POST, PUT, PATCH, and DELETE are handled by the `action`:
+
+```tsx
+import type { Route } from "./+types/resource";
+
+export function loader(_: Route.LoaderArgs) {
+  return Response.json({ message: "I handle GET" });
+}
+
+export function action(_: Route.ActionArgs) {
+  return Response.json({
+    message: "I handle everything else",
+  });
+}
+```
+
+## Return Types
+
+Resource Routes are flexible when it comes to the return type - you can return [`Response`][Response] instances or [`data()`][data] objects. A good general rule of thumb when deciding which type to use is:
+
+- If you're using resource routes intended for external consumption, return `Response` instances
+  - Keeps the resulting response encoding explicit in your code rather than having to wonder how React Router might convert `data() -> Response` under the hood
+- If you're accessing resource routes from [fetchers][fetcher] or [`<Form>`][form] submissions, return `data()`
+  - Keeps things consistent with the loaders/actions in your UI routes
+  - Allows you to stream promises down to your UI through `data()`/[`Await`][await]
+
+## Error Handling
+
+Throwing an `Error` from Resource route (or anything other than a `Response`/`data()`) will trigger [`handleError`][handleError] and result in a 500 HTTP Response:
+
+```tsx
+export function action() {
+  let db = await getDb();
+  if (!db) {
+    // Fatal error - return a 500 response and trigger `handleError`
+    throw new Error("Could not connect to DB");
+  }
+  // ...
+}
+```
+
+If a resource route generates a `Response` (via `new Response()` or `data()`), it is considered a successful execution and will not trigger `handleError` because the API has successfully produced a Response for the HTTP request. This applies to thrown responses as well as returned responses with a 4xx/5xx status code. This behavior aligns with `fetch()` which does not return a rejected promise on 4xx/5xx Responses.
+
+```tsx
+export function action() {
+  // Non-fatal error - don't trigger `handleError`:
+  throw new Response(
+    { error: "Unauthorized" },
+    { status: 401 },
+  );
+
+  // These 3 are equivalent to the above
+  return new Response(
+    { error: "Unauthorized" },
+    { status: 401 },
+  );
+
+  throw data({ error: "Unauthorized" }, { status: 401 });
+
+  return data({ error: "Unauthorized" }, { status: 401 });
+}
+```
+
+### Error Boundaries
+
+[Error Boundaries][error-boundary] are only applicable when a resource route is accessed from a UI, such as from a [`fetcher`][fetcher] call or a [`<Form>`][form] submission. If you `throw` from your resource route in these cases, it will bubble to the nearest `ErrorBoundary` in the UI.
+
+[handleError]: ../api/framework-conventions/entry.server.tsx#handleerror
+[data]: ../api/utils/data
+[Response]: https://developer.mozilla.org/en-US/docs/Web/API/Response
+[fetcher]: ../api/hooks/useFetcher
+[form]: ../api/components/Form
+[await]: ../api/components/Await
+[error-boundary]: ../start/framework/route-module#errorboundary

package/docs/how-to/route-module-type-safety.md

@@ -0,0 +1,100 @@
+---
+title: Route Module Type Safety
+---
+
+# Route Module Type Safety
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+React Router generates route-specific types to power type inference for URL params, loader data, and more.
+This guide will help you set it up if you didn't start with a template.
+
+To learn more about how type safety works in React Router, check out [Type Safety Explanation](../explanation/type-safety).
+
+## 1. Add `.react-router/` to `.gitignore`
+
+React Router generates types into a `.react-router/` directory at the root of your app. This directory is fully managed by React Router and should be gitignore'd.
+
+```txt
+.react-router/
+```
+
+## 2. Include the generated types in tsconfig
+
+Edit your tsconfig to get TypeScript to use the generated types. Additionally, `rootDirs` needs to be configured so the types can be imported as relative siblings to route modules.
+
+```json filename=tsconfig.json
+{
+  "include": [".react-router/types/**/*"],
+  "compilerOptions": {
+    "rootDirs": [".", "./.react-router/types"]
+  }
+}
+```
+
+If you are using multiple `tsconfig` files for your app, you'll need to make these changes in whichever one `include`s your app directory.
+For example, the [`node-custom-server` template](https://github.com/remix-run/react-router-templates/tree/390fcec476dd336c810280479688fe893da38713/node-custom-server) contains `tsconfig.json`, `tsconfig.node.json`, and `tsconfig.vite.json`. Since `tsconfig.vite.json` is the one that [includes the app directory](https://github.com/remix-run/react-router-templates/blob/390fcec476dd336c810280479688fe893da38713/node-custom-server/tsconfig.vite.json#L4-L6), that's the one that sets up `.react-router/types` for route module type safety.
+
+## 3. Generate types before type checking
+
+If you want to run type checking as its own command — for example, as part of your Continuous Integration pipeline — you'll need to make sure to generate types _before_ running typechecking:
+
+```json
+{
+  "scripts": {
+    "typecheck": "react-router typegen && tsc"
+  }
+}
+```
+
+## 4. Typing `AppLoadContext`
+
+## Extending app `Context` types
+
+To define your app's `context` type, add the following in a `.ts` or `.d.ts` file within your project:
+
+```typescript
+import "react-router";
+declare module "react-router" {
+  interface AppLoadContext {
+    // add context properties here
+  }
+}
+```
+
+## 5. Type-only auto-imports (optional)
+
+When auto-importing the `Route` type helper, TypeScript will generate:
+
+```ts filename=app/routes/my-route.tsx
+import { Route } from "./+types/my-route";
+```
+
+But if you enable [verbatimModuleSyntax](https://www.typescriptlang.org/tsconfig/#verbatimModuleSyntax):
+
+```json filename=tsconfig.json
+{
+  "compilerOptions": {
+    "verbatimModuleSyntax": true
+  }
+}
+```
+
+Then, you will get the `type` modifier for the import automatically as well:
+
+```ts filename=app/routes/my-route.tsx
+import type { Route } from "./+types/my-route";
+//     ^^^^
+```
+
+This helps tools like bundlers to detect type-only module that can be safely excluded from the bundle.
+
+## Conclusion
+
+React Router's Vite plugin should be automatically generating types into `.react-router/types/` anytime you edit your route config (`routes.ts`).
+That means all you need to do is run `react-router dev` (or your custom dev server) to get to up-to-date types in your routes.
+
+Check out our [Type Safety Explanation](../explanation/type-safety) for an example of how to pull in those types into your routes.

package/docs/how-to/search-params.md

@@ -0,0 +1,4 @@
+---
+title: Using Search Params
+hidden: true
+---

package/docs/how-to/security.md

@@ -0,0 +1,30 @@
+---
+title: Security
+---
+
+# Security
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+This is by no means a comprehensive guide, but React Router provides features to help address a few aspects under the _very large_ umbrella that is _Security_.
+
+## `Content-Security-Policy`
+
+If you are implementing a [Content-Security-Policy (CSP)][csp] in your application, specifically one using the `unsafe-inline` directive, you will need to specify a [`nonce`][nonce] attribute on the inline `<script>` elements rendered in your HTML. This must be specified on any API that generates inline scripts, including:
+
+- [`<Scripts nonce>`][scripts] (`root.tsx`)
+- [`<ScrollRestoration nonce>`][scrollrestoration] (`root.tsx`)
+- [`<ServerRouter nonce>`][serverrouter] (`entry.server.tsx`)
+- [`renderToPipeableStream(..., { nonce })`][renderToPipeableStream] (`entry.server.tsx`)
+- [`renderToReadableStream(..., { nonce })`][renderToReadableStream] (`entry.server.tsx`)
+
+[csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP
+[nonce]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce
+[renderToPipeableStream]: https://react.dev/reference/react-dom/server/renderToPipeableStream
+[renderToReadableStream]: https://react.dev/reference/react-dom/server/renderToReadableStream
+[scripts]: ../api/components/Scripts
+[scrollrestoration]: ../api/components/ScrollRestoration
+[serverrouter]: ../api/components/ServerRouter

package/docs/how-to/server-bundles.md

@@ -0,0 +1,66 @@
+---
+title: Server Bundles
+---
+
+# Server Bundles
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+<docs-warning>This is an advanced feature designed for hosting provider integrations. When compiling your app into multiple server bundles, there will need to be a custom routing layer in front of your app directing requests to the correct bundle.</docs-warning>
+
+React Router typically builds your server code into a single bundle that exports a request handler function. However, there are scenarios where you might want to split your route tree into multiple server bundles, each exposing a request handler function for a subset of routes. To provide this flexibility, [`react-router.config.ts`][react-router-config] supports a `serverBundles` option, which is a function for assigning routes to different server bundles.
+
+The [`serverBundles` function][server-bundles-function] is called for each route in the tree (except for routes that aren't addressable, e.g., pathless layout routes) and returns a server bundle ID that you'd like to assign that route to. These bundle IDs will be used as directory names in your server build directory.
+
+For each route, this function receives an array of routes leading to and including that route, referred to as the route `branch`. This allows you to create server bundles for different portions of the route tree. For example, you could use this to create a separate server bundle containing all routes within a particular layout route:
+
+```ts filename=react-router.config.ts lines=[5-13]
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  // ...
+  serverBundles: ({ branch }) => {
+    const isAuthenticatedRoute = branch.some((route) =>
+      route.id.split("/").includes("_authenticated"),
+    );
+
+    return isAuthenticatedRoute
+      ? "authenticated"
+      : "unauthenticated";
+  },
+} satisfies Config;
+```
+
+Each `route` in the `branch` array contains the following properties:
+
+- `id` — The unique ID for this route, named like its `file` but relative to the app directory and without the extension, e.g., `app/routes/gists.$username.tsx` will have an `id` of `routes/gists.$username`
+- `path` — The path this route uses to match the URL pathname
+- `file` — The absolute path to the entry point for this route
+- `index` — Whether this route is an index route
+
+## Build manifest
+
+When the build is complete, React Router will call the `buildEnd` hook, passing a `buildManifest` object. This is useful if you need to inspect the build manifest to determine how to route requests to the correct server bundle.
+
+```ts filename=react-router.config.ts lines=[5-7]
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  // ...
+  buildEnd: async ({ buildManifest }) => {
+    // ...
+  },
+} satisfies Config;
+```
+
+When using server bundles, the build manifest contains the following properties:
+
+- `serverBundles` — An object that maps bundle IDs to the bundle's `id` and `file`
+- `routeIdToServerBundleId` — An object that maps route IDs to their server bundle ID
+- `routes` — A route manifest that maps route IDs to route metadata. This can be used to drive a custom routing layer in front of your React Router request handlers
+
+[react-router-config]: https://api.reactrouter.com/v7/types/_react-router_dev.config.Config.html
+[server-bundles-function]: https://api.reactrouter.com/v7/types/_react-router_dev.config.ServerBundlesFunction.html

package/docs/how-to/spa.md

@@ -0,0 +1,120 @@
+---
+title: Single Page App (SPA)
+---
+
+# Single Page App (SPA)
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+<docs-info>This guide focuses on how to build Single Page Apps with React Router Framework mode. If you're using React Router in declarative or data mode, you can design your own SPA architecture.</docs-info>
+
+When using React Router as a framework, you can enable "SPA Mode" by setting `ssr:false` in your `react-router.config.ts` file. This will disable runtime server rendering and generate an `index.html` at build time that you can serve and hydrate as a SPA.
+
+Typical Single Page apps send a mostly blank `index.html` template with little more than an empty `<div id="root"></div>`. In contrast, `react-router build` (in SPA Mode) pre-renders your root route at build time into an `index.html` file. This means you can:
+
+- Send more than an empty `<div>`
+- Use a root `loader` to load data for your application shell
+- Use React components to generate the initial page users see (root `HydrateFallback`)
+- Re-enable server rendering later without changing anything about your UI
+
+<docs-info>SPA Mode is a special form of "Pre-Rendering" that allows you to serve all paths in your application from the same HTML file. Please refer to the [Pre-Rendering](./pre-rendering) guide if you want to do more extensive pre-rendering.</docs-info>
+
+## 1. Disable Runtime Server Rendering
+
+Server rendering is enabled by default. Set the `ssr` flag to `false` in `react-router.config.ts` to disable it.
+
+```ts filename=react-router.config.ts lines=[4]
+import { type Config } from "@react-router/dev/config";
+
+export default {
+  ssr: false,
+} satisfies Config;
+```
+
+With this set to false, the server build will no longer be generated.
+
+<docs-info>It's important to note that setting `ssr:false` only disables _runtime server rendering_. React Router will still server render your root route at _build time_ to generate the `index.html` file. This is why your project still needs a dependency on `@react-router/node` and your routes need to be SSR-safe. That means you can't call `window` or other browser-only APIs during the initial render, even when server rendering is disabled.</docs-info>
+
+## 2. Add a `HydrateFallback` and optional `loader` to your root route
+
+SPA Mode will generate an `index.html` file at build-time that you can serve as the entry point for your SPA. This will only render the root route so that it is capable of hydrating at runtime for any path in your application.
+
+To provide a better loading UI than an empty `<div>`, you can add a `HydrateFallback` component to your root route to render your loading UI into the `index.html` at build time. This way, it will be shown to users immediately while the SPA is loading/hydrating.
+
+```tsx filename=root.tsx lines=[7-9]
+import LoadingScreen from "./components/loading-screen";
+
+export function Layout() {
+  return <html>{/*...*/}</html>;
+}
+
+export function HydrateFallback() {
+  return <LoadingScreen />;
+}
+
+export default function App() {
+  return <Outlet />;
+}
+```
+
+Because the root route is server-rendered at build time, you can also use a `loader` in your root route if you choose. This `loader` will be called at build time and the data will be available via the optional `HydrateFallback` `loaderData` prop.
+
+```tsx filename=root.tsx lines=[5,10,14]
+import { Route } from "./+types/root";
+
+export async function loader() {
+  return {
+    version: await getVersion(),
+  };
+}
+
+export function HydrateFallback({
+  loaderData,
+}: Route.ComponentProps) {
+  return (
+    <div>
+      <h1>Loading version {loaderData.version}...</h1>
+      <AwesomeSpinner />
+    </div>
+  );
+}
+```
+
+You cannot include a `loader` in any other routes in your app when using SPA Mode unless you are [pre-rendering those pages](./pre-rendering).
+
+## 3. Use client loaders and client actions
+
+With server rendering disabled, you can still use `clientLoader` and `clientAction` to manage route data and mutations.
+
+```tsx filename=some-route.tsx
+import { Route } from "./+types/some-route";
+
+export async function clientLoader({
+  params,
+}: Route.ClientLoaderArgs) {
+  let data = await fetch(`/some/api/stuff/${params.id}`);
+  return data;
+}
+
+export async function clientAction({
+  request,
+}: Route.ClientActionArgs) {
+  let formData = await request.formData();
+  return await processPayment(formData);
+}
+```
+
+## 4. Direct all URLs to index.html
+
+After running `react-router build`, deploy the `build/client` directory to whatever static host you prefer.
+
+Common to deploying any SPA, you'll need to configure your host to direct all URLs to the `index.html` of the client build. Some hosts do this by default, but others don't. As an example, a host may support a `_redirects` file to do this:
+
+```
+/*    /index.html   200
+```
+
+If you're getting 404s at valid routes for your app, it's likely you need to configure your host.

package/docs/how-to/status.md

@@ -0,0 +1,63 @@
+---
+title: Status Codes
+---
+
+# Status Codes
+
+[MODES: framework ,data]
+
+<br/>
+<br/>
+
+Set status codes from loaders and actions with `data`.
+
+```tsx filename=app/project.tsx lines=[3,12-15,20,23]
+// route('/projects/:projectId', './project.tsx')
+import type { Route } from "./+types/project";
+import { data } from "react-router";
+import { fakeDb } from "../db";
+
+export async function action({
+  request,
+}: Route.ActionArgs) {
+  let formData = await request.formData();
+  let title = formData.get("title");
+  if (!title) {
+    return data(
+      { message: "Invalid title" },
+      { status: 400 },
+    );
+  }
+
+  if (!projectExists(title)) {
+    let project = await fakeDb.createProject({ title });
+    return data(project, { status: 201 });
+  } else {
+    let project = await fakeDb.updateProject({ title });
+    // the default status code is 200, no need for `data`
+    return project;
+  }
+}
+```
+
+See [Form Validation](./form-validation) for more information on rendering form errors like this.
+
+Another common status code is 404:
+
+```tsx
+// route('/projects/:projectId', './project.tsx')
+import type { Route } from "./+types/project";
+import { data } from "react-router";
+import { fakeDb } from "../db";
+
+export async function loader({ params }: Route.ActionArgs) {
+  let project = await fakeDb.getProject(params.id);
+  if (!project) {
+    // throw to ErrorBoundary
+    throw data(null, { status: 404 });
+  }
+  return project;
+}
+```
+
+See the [Error Boundaries](./error-boundary) for more information on thrown `data`.

package/docs/how-to/suspense.md

@@ -0,0 +1,132 @@
+---
+title: Streaming with Suspense
+---
+
+# Streaming with Suspense
+
+[MODES: framework, data]
+
+<br/>
+<br/>
+
+Streaming with React Suspense allows apps to speed up initial renders by deferring non-critical data and unblocking UI rendering.
+
+React Router supports React Suspense by returning promises from loaders and actions.
+
+## 1. Return a promise from loader
+
+React Router awaits route loaders before rendering route components. To unblock the loader for non-critical data, return the promise instead of awaiting it in the loader.
+
+```tsx
+import type { Route } from "./+types/my-route";
+
+export async function loader({}: Route.LoaderArgs) {
+  // note this is NOT awaited
+  let nonCriticalData = new Promise((res) =>
+    setTimeout(() => res("non-critical"), 5000),
+  );
+
+  let criticalData = await new Promise((res) =>
+    setTimeout(() => res("critical"), 300),
+  );
+
+  return { nonCriticalData, criticalData };
+}
+```
+
+Note you can't return a single promise, it must be an object with keys.
+
+## 2. Render the fallback and resolved UI
+
+The promise will be available on `loaderData`, `<Await>` will await the promise and trigger `<Suspense>` to render the fallback UI.
+
+```tsx
+import * as React from "react";
+import { Await } from "react-router";
+
+// [previous code]
+
+export default function MyComponent({
+  loaderData,
+}: Route.ComponentProps) {
+  let { criticalData, nonCriticalData } = loaderData;
+
+  return (
+    <div>
+      <h1>Streaming example</h1>
+      <h2>Critical data value: {criticalData}</h2>
+
+      <React.Suspense fallback={<div>Loading...</div>}>
+        <Await resolve={nonCriticalData}>
+          {(value) => <h3>Non critical value: {value}</h3>}
+        </Await>
+      </React.Suspense>
+    </div>
+  );
+}
+```
+
+## With React 19
+
+If you're using React 19, you can use `React.use` instead of `Await`, but you'll need to create a new component and pass the promise down to trigger the suspense fallback.
+
+```tsx
+<React.Suspense fallback={<div>Loading...</div>}>
+  <NonCriticalUI p={nonCriticalData} />
+</React.Suspense>
+```
+
+```tsx
+function NonCriticalUI({ p }: { p: Promise<string> }) {
+  let value = React.use(p);
+  return <h3>Non critical value {value}</h3>;
+}
+```
+
+## Timeouts
+
+By default, loaders and actions reject any outstanding promises after 4950ms. You can control this by exporting a `streamTimeout` numerical value from your `entry.server.tsx`.
+
+```ts filename=entry.server.tsx
+// Reject all pending promises from handler functions after 10 seconds
+export const streamTimeout = 10_000;
+```
+
+## Handling early rejections (Node)
+
+React Router waits for all loaders to settle (via `Promise.all`) before it begins streaming the response. Once streaming has started, React Router catches subsequent rejections of your streamed promises and surfaces them to your `<Await>` (or React 19 `React.use`) error UI.
+
+However, if a streamed promise rejects _before_ all of the route's loaders have settled, React Router has not yet been able to attach a handler to it. In Node, an unhandled promise rejection will crash the process unless you have a top-level handler registered.
+
+For example, this can happen if a parent route's loader takes longer to resolve than a child route's streamed promise takes to reject:
+
+```tsx
+// parent.tsx — slow loader
+export async function loader() {
+  await new Promise((r) => setTimeout(r, 1000));
+  return { parent: "data" };
+}
+
+// child.tsx — fast-rejecting streamed promise
+export async function loader() {
+  let lazy = new Promise((_, reject) =>
+    setTimeout(() => reject(new Error("boom")), 100),
+  );
+  return { lazy };
+}
+```
+
+When `lazy` rejects before the parent loader resolves, the rejection bubbles to the node process as an unhandled rejection, which will crash the process without a user-defined handler.
+
+To prevent this, register a process-level `unhandledRejection` handler in your server entry:
+
+```ts filename=entry.server.ts
+process.on("unhandledRejection", (reason, promise) => {
+  console.error(
+    "Unhandled Rejection at:",
+    promise,
+    "reason:",
+    reason,
+  );
+});
+```