react-router 7.16.0 → 7.17.0

package/docs/start/declarative/url-values.md

@@ -0,0 +1,65 @@
+---
+title: URL Values
+---
+
+# URL Values
+
+[MODES: declarative]
+
+## Route Params
+
+Route params are the parsed values from a dynamic segment.
+
+```tsx
+<Route path="/concerts/:city" element={<City />} />
+```
+
+In this case, `:city` is the dynamic segment. The parsed value for that city will be available from `useParams`
+
+```tsx
+import { useParams } from "react-router";
+
+function City() {
+  let { city } = useParams();
+  let data = useFakeDataLibrary(`/api/v2/cities/${city}`);
+  // ...
+}
+```
+
+## URL Search Params
+
+Search params are the values after a `?` in the URL. They are accessible from `useSearchParams`, which returns an instance of [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)
+
+```tsx
+function SearchResults() {
+  let [searchParams] = useSearchParams();
+  return (
+    <div>
+      <p>
+        You searched for <i>{searchParams.get("q")}</i>
+      </p>
+      <FakeSearchResults />
+    </div>
+  );
+}
+```
+
+## Location Object
+
+React Router creates a custom `location` object with some useful information on it accessible with `useLocation`.
+
+```tsx
+function useAnalytics() {
+  let location = useLocation();
+  useEffect(() => {
+    sendFakeAnalytics(location.pathname);
+  }, [location]);
+}
+
+function useScrollRestoration() {
+  let location = useLocation();
+  useEffect(() => {
+    fakeRestoreScroll(location.key);
+  }, [location]);
+}
+```

package/docs/start/framework/actions.md

@@ -0,0 +1,174 @@
+---
+title: Actions
+order: 6
+---
+
+# Actions
+
+[MODES: framework]
+
+## Introduction
+
+Data mutations are done through Route actions. When the action completes, all loader data on the page is revalidated to keep your UI in sync with the data without writing any code to do it.
+
+Route actions defined with `action` are only called on the server while actions defined with `clientAction` are run in the browser.
+
+## Client Actions
+
+Client actions only run in the browser and take priority over a server action when both are defined.
+
+```tsx filename=app/project.tsx
+// route('/projects/:projectId', './project.tsx')
+import type { Route } from "./+types/project";
+import { Form } from "react-router";
+import { someApi } from "./api";
+
+export async function clientAction({
+  request,
+}: Route.ClientActionArgs) {
+  let formData = await request.formData();
+  let title = formData.get("title");
+  let project = await someApi.updateProject({ title });
+  return project;
+}
+
+export default function Project({
+  actionData,
+}: Route.ComponentProps) {
+  return (
+    <div>
+      <h1>Project</h1>
+      <Form method="post">
+        <input type="text" name="title" />
+        <button type="submit">Submit</button>
+      </Form>
+      {actionData ? (
+        <p>{actionData.title} updated</p>
+      ) : null}
+    </div>
+  );
+}
+```
+
+## Server Actions
+
+Server actions only run on the server and are removed from client bundles.
+
+```tsx filename=app/project.tsx
+// route('/projects/:projectId', './project.tsx')
+import type { Route } from "./+types/project";
+import { Form } from "react-router";
+import { fakeDb } from "../db";
+
+export async function action({
+  request,
+}: Route.ActionArgs) {
+  let formData = await request.formData();
+  let title = formData.get("title");
+  let project = await fakeDb.updateProject({ title });
+  return project;
+}
+
+export default function Project({
+  actionData,
+}: Route.ComponentProps) {
+  return (
+    <div>
+      <h1>Project</h1>
+      <Form method="post">
+        <input type="text" name="title" />
+        <button type="submit">Submit</button>
+      </Form>
+      {actionData ? (
+        <p>{actionData.title} updated</p>
+      ) : null}
+    </div>
+  );
+}
+```
+
+## Calling Actions
+
+Actions are called declaratively through `<Form>` and imperatively through `useSubmit` (or `<fetcher.Form>` and `fetcher.submit`) by referencing the route's path and a "post" method.
+
+### Calling actions with a Form
+
+```tsx
+import { Form } from "react-router";
+
+function SomeComponent() {
+  return (
+    <Form action="/projects/123" method="post">
+      <input type="text" name="title" />
+      <button type="submit">Submit</button>
+    </Form>
+  );
+}
+```
+
+This will cause a navigation and a new entry will be added to the browser history.
+
+### Calling actions with useSubmit
+
+You can submit form data to an action imperatively with `useSubmit`.
+
+```tsx
+import { useCallback } from "react";
+import { useSubmit } from "react-router";
+import { useFakeTimer } from "fake-lib";
+
+function useQuizTimer() {
+  let submit = useSubmit();
+
+  let cb = useCallback(() => {
+    submit(
+      { quizTimedOut: true },
+      { action: "/end-quiz", method: "post" },
+    );
+  }, []);
+
+  let tenMinutes = 10 * 60 * 1000;
+  useFakeTimer(tenMinutes, cb);
+}
+```
+
+This will cause a navigation and a new entry will be added to the browser history.
+
+### Calling actions with a fetcher
+
+Fetchers allow you to submit data to actions (and loaders) without causing a navigation (no new entries in the browser history).
+
+```tsx
+import { useFetcher } from "react-router";
+
+function Task() {
+  let fetcher = useFetcher();
+  let busy = fetcher.state !== "idle";
+
+  return (
+    <fetcher.Form method="post" action="/update-task/123">
+      <input type="text" name="title" />
+      <button type="submit">
+        {busy ? "Saving..." : "Save"}
+      </button>
+    </fetcher.Form>
+  );
+}
+```
+
+They also have the imperative `submit` method.
+
+```tsx
+fetcher.submit(
+  { title: "New Title" },
+  { action: "/update-task/123", method: "post" },
+);
+```
+
+See the [Using Fetchers][fetchers] guide for more information.
+
+---
+
+Next: [Navigating](./navigating)
+
+[fetchers]: ../../how-to/fetchers

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

@@ -0,0 +1,201 @@
+---
+title: Data Loading
+order: 5
+---
+
+# Data Loading
+
+[MODES: framework]
+
+## Introduction
+
+Data is provided to the route component from `loader` and `clientLoader`.
+
+Loader data is automatically serialized from loaders and deserialized in components. In addition to primitive values like strings and numbers, loaders can return promises, maps, sets, dates and more.
+
+The type for the `loaderData` prop is [automatically generated][type-safety].
+
+<docs-info>We try to support the same set of [serializable types][serializable-types] that React permits server components to pass as props to client components. This future proofs your application for any eventual migration to [RSC][rsc].</docs-info>
+
+## Client Data Loading
+
+`clientLoader` is used to fetch data on the client. This is useful for pages or full projects that you'd prefer to fetch data from the browser only.
+
+```tsx filename=app/product.tsx
+// route("products/:pid", "./product.tsx");
+import type { Route } from "./+types/product";
+
+export async function clientLoader({
+  params,
+}: Route.ClientLoaderArgs) {
+  const res = await fetch(`/api/products/${params.pid}`);
+  const product = await res.json();
+  return product;
+}
+
+// HydrateFallback is rendered while the client loader is running
+export function HydrateFallback() {
+  return <div>Loading...</div>;
+}
+
+export default function Product({
+  loaderData,
+}: Route.ComponentProps) {
+  const { name, description } = loaderData;
+  return (
+    <div>
+      <h1>{name}</h1>
+      <p>{description}</p>
+    </div>
+  );
+}
+```
+
+## Server Data Loading
+
+When server rendering, `loader` is used for both initial page loads and client navigations. Client navigations call the loader through an automatic `fetch` by React Router from the browser to your server.
+
+```tsx filename=app/product.tsx
+// route("products/:pid", "./product.tsx");
+import type { Route } from "./+types/product";
+import { fakeDb } from "../db";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  const product = await fakeDb.getProduct(params.pid);
+  return product;
+}
+
+export default function Product({
+  loaderData,
+}: Route.ComponentProps) {
+  const { name, description } = loaderData;
+  return (
+    <div>
+      <h1>{name}</h1>
+      <p>{description}</p>
+    </div>
+  );
+}
+```
+
+Note that the `loader` function is removed from client bundles so you can use server only APIs without worrying about them being included in the browser.
+
+## Static Data Loading
+
+When pre-rendering, loaders are used to fetch data during the production build.
+
+```tsx filename=app/product.tsx
+// route("products/:pid", "./product.tsx");
+import type { Route } from "./+types/product";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  let product = await getProductFromCSVFile(params.pid);
+  return product;
+}
+
+export default function Product({
+  loaderData,
+}: Route.ComponentProps) {
+  const { name, description } = loaderData;
+  return (
+    <div>
+      <h1>{name}</h1>
+      <p>{description}</p>
+    </div>
+  );
+}
+```
+
+The URLs to pre-render are specified in `react-router.config.ts`:
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  async prerender() {
+    let products = await readProductsFromCSVFile();
+    return products.map(
+      (product) => `/products/${product.id}`,
+    );
+  },
+} satisfies Config;
+```
+
+Note that when server rendering, any URLs that aren't pre-rendered will be server rendered as usual, allowing you to pre-render some data at a single route while still server rendering the rest.
+
+## Using Both Loaders
+
+`loader` and `clientLoader` can be used together. The `loader` will be used on the server for initial SSR (or pre-rendering) and the `clientLoader` will be used on subsequent client-side navigations.
+
+```tsx filename=app/product.tsx
+// route("products/:pid", "./product.tsx");
+import type { Route } from "./+types/product";
+import { fakeDb } from "../db";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  return fakeDb.getProduct(params.pid);
+}
+
+export async function clientLoader({
+  serverLoader,
+  params,
+}: Route.ClientLoaderArgs) {
+  const res = await fetch(`/api/products/${params.pid}`);
+  const serverData = await serverLoader();
+  return { ...serverData, ...(await res.json()) };
+}
+
+export default function Product({
+  loaderData,
+}: Route.ComponentProps) {
+  const { name, description } = loaderData;
+
+  return (
+    <div>
+      <h1>{name}</h1>
+      <p>{description}</p>
+    </div>
+  );
+}
+```
+
+You can also force the client loader to run during hydration and before the page renders by setting the `hydrate` property on the function. In this situation you will want to render a `HydrateFallback` component to show a fallback UI while the client loader runs.
+
+```tsx filename=app/product.tsx
+export async function loader() {
+  /* ... */
+}
+
+export async function clientLoader() {
+  /* ... */
+}
+
+// force the client loader to run during hydration
+clientLoader.hydrate = true as const; // `as const` for type inference
+
+export function HydrateFallback() {
+  return <div>Loading...</div>;
+}
+
+export default function Product() {
+  /* ... */
+}
+```
+
+---
+
+Next: [Actions][actions]
+
+See also:
+
+- [Streaming with Suspense][streaming]
+- [Client Data][client-data]
+- [Using Fetchers][fetchers]
+
+[type-safety]: ../../explanation/type-safety
+[serializable-types]: https://react.dev/reference/rsc/use-client#serializable-types
+[rsc]: ../../how-to/react-server-components
+[actions]: ./actions
+[streaming]: ../../how-to/suspense
+[client-data]: ../../how-to/client-data
+[fetchers]: ../../how-to/fetchers#loading-data

package/docs/start/framework/deploying.md

@@ -0,0 +1,96 @@
+---
+title: Deploying
+order: 10
+---
+
+# Deploying
+
+[MODES: framework]
+
+## Introduction
+
+React Router can be deployed two ways:
+
+- Fullstack Hosting
+- Static Hosting
+
+The official [React Router templates](https://github.com/remix-run/react-router-templates) can help you bootstrap an application or be used as a reference for your own application.
+
+When deploying to static hosting, you can deploy React Router the same as any other single page application with React.
+
+## Templates
+
+After running the `create-react-router` command, make sure to follow the instructions in the README.
+
+### Node.js with Docker
+
+```
+npx create-react-router@latest --template remix-run/react-router-templates/default
+```
+
+- Server Rendering
+- Tailwind CSS
+
+The containerized application can be deployed to any platform that supports Docker, including:
+
+- AWS ECS
+- Google Cloud Run
+- Azure Container Apps
+- Digital Ocean App Platform
+- Fly.io
+- Railway
+
+### Node with Docker (Custom Server)
+
+```
+npx create-react-router@latest --template remix-run/react-router-templates/node-custom-server
+```
+
+- Server Rendering
+- Tailwind CSS
+- Custom express server for more control
+
+The containerized application can be deployed to any platform that supports Docker, including:
+
+- AWS ECS
+- Google Cloud Run
+- Azure Container Apps
+- Digital Ocean App Platform
+- Fly.io
+- Railway
+
+### Node with Docker and Postgres
+
+```
+npx create-react-router@latest --template remix-run/react-router-templates/node-postgres
+```
+
+- Server Rendering
+- Postgres Database with Drizzle
+- Tailwind CSS
+- Custom express server for more control
+
+The containerized application can be deployed to any platform that supports Docker, including:
+
+- AWS ECS
+- Google Cloud Run
+- Azure Container Apps
+- Digital Ocean App Platform
+- Fly.io
+- Railway
+
+### Vercel
+
+Vercel maintains their own template for React Router. Checkout the [Vercel Guide](https://vercel.com/templates/react-router/react-router-boilerplate) for more information.
+
+### Cloudflare Workers
+
+Cloudflare maintains their own template for React Router. Checkout the [Cloudflare Guide](https://developers.cloudflare.com/workers/framework-guides/web-apps/react-router/) for more information.
+
+### Netlify
+
+Netlify maintains their own template for React Router. Checkout the [Netlify Guide](https://docs.netlify.com/build/frameworks/framework-setup-guides/react-router/) for more information.
+
+### EdgeOne Pages
+
+EdgeOne Pages maintains their own template for React Router. Checkout the [EdgeOne Pages Guide](https://pages.edgeone.ai/document/framework-react-router) for more information.

package/docs/start/framework/index.md

@@ -0,0 +1,4 @@
+---
+title: Framework Mode
+order: 2
+---

package/docs/start/framework/installation.md

@@ -0,0 +1,41 @@
+---
+title: Installation
+order: 1
+---
+
+# Installation
+
+[MODES: framework]
+
+## Introduction
+
+Most projects start with a template. Let's use a basic template maintained by React Router:
+
+```shellscript nonumber
+npx create-react-router@latest my-react-router-app
+```
+
+Now change into the new directory and start the app
+
+```shellscript nonumber
+cd my-react-router-app
+npm i
+npm run dev
+```
+
+You can now open your browser to `http://localhost:5173`
+
+You can [view the template on GitHub][default-template] to see how to manually set up your project.
+
+We also have a number of [ready to deploy templates][react-router-templates] available for you to get started with:
+
+```shellscript nonumber
+npx create-react-router@latest --template remix-run/react-router-templates/<template-name>
+```
+
+---
+
+Next: [Routing](./routing)
+
+[default-template]: https://github.com/remix-run/react-router-templates/tree/main/default
+[react-router-templates]: https://github.com/remix-run/react-router-templates