react-router 7.16.0 → 7.17.0

package/docs/how-to/navigation-blocking.md

@@ -0,0 +1,233 @@
+---
+title: Navigation Blocking
+---
+
+# Navigation Blocking
+
+[MODES: framework, data]
+
+<br/>
+<br/>
+
+When users are in the middle of a workflow, like filling out an important form, you may want to prevent them from navigating away from the page.
+
+This example will show:
+
+- Setting up a route with a form and action called with a fetcher
+- Blocking navigation when the form is dirty
+- Showing a confirmation when the user tries to leave the page
+
+## 1. Set up a route with a form
+
+Add a route with the form, we'll use a "contact" route for this example:
+
+```ts filename=routes.ts
+import {
+  type RouteConfig,
+  index,
+  route,
+} from "@react-router/dev/routes";
+
+export default [
+  index("routes/home.tsx"),
+  route("contact", "routes/contact.tsx"),
+] satisfies RouteConfig;
+```
+
+Add the form to the contact route module:
+
+```tsx filename=routes/contact.tsx
+import { useFetcher } from "react-router";
+import type { Route } from "./+types/contact";
+
+export async function action({
+  request,
+}: Route.ActionArgs) {
+  let formData = await request.formData();
+  let email = formData.get("email");
+  let message = formData.get("message");
+  console.log(email, message);
+  return { ok: true };
+}
+
+export default function Contact() {
+  let fetcher = useFetcher();
+
+  return (
+    <fetcher.Form method="post">
+      <p>
+        <label>
+          Email: <input name="email" type="email" />
+        </label>
+      </p>
+      <p>
+        <textarea name="message" />
+      </p>
+      <p>
+        <button type="submit">
+          {fetcher.state === "idle" ? "Send" : "Sending..."}
+        </button>
+      </p>
+    </fetcher.Form>
+  );
+}
+```
+
+## 2. Add dirty state and onChange handler
+
+To track the dirty state of the form, we'll use a single boolean and a quick form onChange handler. You may want to track the dirty state differently but this works for this guide.
+
+```tsx filename=routes/contact.tsx lines=[2,8-12]
+export default function Contact() {
+  let [isDirty, setIsDirty] = useState(false);
+  let fetcher = useFetcher();
+
+  return (
+    <fetcher.Form
+      method="post"
+      onChange={(event) => {
+        let email = event.currentTarget.email.value;
+        let message = event.currentTarget.message.value;
+        setIsDirty(Boolean(email || message));
+      }}
+    >
+      {/* existing code */}
+    </fetcher.Form>
+  );
+}
+```
+
+## 3. Block navigation when the form is dirty
+
+```tsx filename=routes/contact.tsx lines=[1,6-8]
+import { useBlocker } from "react-router";
+
+export default function Contact() {
+  let [isDirty, setIsDirty] = useState(false);
+  let fetcher = useFetcher();
+  let blocker = useBlocker(
+    useCallback(() => isDirty, [isDirty]),
+  );
+
+  // ... existing code
+}
+```
+
+While this will now block a navigation, there's no way for the user to confirm it.
+
+## 4. Show confirmation UI
+
+This uses a simple div, but you may want to use a modal dialog.
+
+```tsx filename=routes/contact.tsx lines=[19-41]
+export default function Contact() {
+  let [isDirty, setIsDirty] = useState(false);
+  let fetcher = useFetcher();
+  let blocker = useBlocker(
+    useCallback(() => isDirty, [isDirty]),
+  );
+
+  return (
+    <fetcher.Form
+      method="post"
+      onChange={(event) => {
+        let email = event.currentTarget.email.value;
+        let message = event.currentTarget.message.value;
+        setIsDirty(Boolean(email || message));
+      }}
+    >
+      {/* existing code */}
+
+      {blocker.state === "blocked" && (
+        <div>
+          <p>Wait! You didn't send the message yet:</p>
+          <p>
+            <button
+              type="button"
+              onClick={() => blocker.proceed()}
+            >
+              Leave
+            </button>{" "}
+            <button
+              type="button"
+              onClick={() => blocker.reset()}
+            >
+              Stay here
+            </button>
+          </p>
+        </div>
+      )}
+    </fetcher.Form>
+  );
+}
+```
+
+If the user clicks "leave" then `blocker.proceed()` will proceed with the navigation. If they click "stay here" then `blocker.reset()` will clear the blocker and keep them on the current page.
+
+## 5. Reset the blocker when the action resolves
+
+If the user doesn't click either "leave" or "stay here", then submits the form, the blocker will still be active. Let's reset the blocker when the action resolves with an effect.
+
+```tsx filename=routes/contact.tsx
+useEffect(() => {
+  if (fetcher.data?.ok) {
+    if (blocker.state === "blocked") {
+      blocker.reset();
+    }
+  }
+}, [fetcher.data]);
+```
+
+## 6. Clear the form when the action resolves
+
+While unrelated to navigation blocking, let's clear the form when the action resolves with a ref.
+
+```tsx
+let formRef = useRef<HTMLFormElement>(null);
+
+// put it on the form
+<fetcher.Form
+  ref={formRef}
+  method="post"
+  onChange={(event) => {
+    // ... existing code
+  }}
+>
+  {/* existing code */}
+</fetcher.Form>;
+```
+
+```tsx
+useEffect(() => {
+  if (fetcher.data?.ok) {
+    // clear the form in the effect
+    formRef.current?.reset();
+    if (blocker.state === "blocked") {
+      blocker.reset();
+    }
+  }
+}, [fetcher.data]);
+```
+
+Alternatively, if a navigation is currently blocked, instead of resetting the blocker, you can proceed through to the blocked navigation.
+
+```tsx
+useEffect(() => {
+  if (fetcher.data?.ok) {
+    if (blocker.state === "blocked") {
+      // proceed with the blocked navigation
+      blocker.proceed();
+    } else {
+      formRef.current?.reset();
+    }
+  }
+}, [fetcher.data]);
+```
+
+In this case the user flow is:
+
+- User fills out the form
+- User forgets to click "send" and clicks a link instead
+- The navigation is blocked, and the confirmation message is shown
+- Instead of clicking "leave" or "stay here", the user submits the form
+- The user is taken to the requested page

package/docs/how-to/optimize-revalidation.md

@@ -0,0 +1,12 @@
+---
+title: Revalidation Optimization
+hidden: true
+---
+
+[copy pasted]
+
+During client-side transitions, React Router will optimize reloading of routes that are already rendering, like not reloading layout routes that aren't changing. In other cases, like form submissions or search param changes, React Router doesn't know which routes need to be reloaded, so it reloads them all to be safe. This ensures your UI always stays in sync with the state on your server.
+
+This function lets apps further optimize by returning `false` when React Router is about to reload a route. If you define this function on a route module, React Router will defer to your function on every navigation and every revalidation after an action is called. Again, this makes it possible for your UI to get out of sync with your server if you do it wrong, so be careful.
+
+`fetcher.load` calls also revalidate, but because they load a specific URL, they don't have to worry about route param or URL search param revalidations. `fetcher.load`'s only revalidate by default after action submissions and explicit revalidation requests via [`useRevalidator`][use-revalidator].

package/docs/how-to/pre-rendering.md

@@ -0,0 +1,225 @@
+---
+title: Pre-Rendering
+---
+
+# Pre-Rendering
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+Pre-Rendering allows you to speed up page loads for static content by rendering pages at build time instead of at runtime.
+
+## Configuration
+
+Pre-rendering is enabled via the `prerender` config in `react-router.config.ts`.
+
+The simplest configuration is a boolean `true` which will pre-render all off the applications static paths based on `routes.ts`:
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  prerender: true,
+} satisfies Config;
+```
+
+The boolean `true` will not include any dynamic paths (i.e., `/blog/:slug`) because the parameter values are unknown.
+
+To configure specific paths including dynamic values, you can specify an array of paths:
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+let slugs = getPostSlugs();
+
+export default {
+  prerender: [
+    "/",
+    "/blog",
+    ...slugs.map((s) => `/blog/${s}`),
+  ],
+} satisfies Config;
+```
+
+If you need to perform more complex and/or asynchronous logic to determine the paths, you can also provide a function that returns an array of paths. This function provides you with a `getStaticPaths` method you can use to avoid manually adding all of the static paths in your application:
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  async prerender({ getStaticPaths }) {
+    let slugs = await getPostSlugsFromCMS();
+    return [
+      ...getStaticPaths(), // "/" and "/blog"
+      ...slugs.map((s) => `/blog/${s}`),
+    ];
+  },
+} satisfies Config;
+```
+
+### Concurrency
+
+By default, pages are pre-rendered one path at a time. You can enable concurrency to pre-render multiple paths in parallel which can speed up build times in many cases. You should experiment with the value that provides the best performance for your app.
+
+To specify concurrency, move your `prerender` config down into a `prerender.paths` field and you can specify the concurrency in `prerender.concurrency`:
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+let slugs = getPostSlugs();
+
+export default {
+  prerender: {
+    paths: [
+      "/",
+      "/blog",
+      ...slugs.map((s) => `/blog/${s}`),
+    ],
+    concurrency: 4,
+  },
+} satisfies Config;
+```
+
+## Pre-Rendering with/without a Runtime Server
+
+Pre-Rendering can be used in two ways based on the `ssr` config value:
+
+- Alongside a runtime SSR server with `ssr:true` (the default value)
+- Deployed to a static file server with `ssr:false`
+
+### Pre-rendering with `ssr:true`
+
+When pre-rendering with `ssr:true`, you're indicating you will still have a runtime server but you are choosing to pre-render certain paths for quicker Response times.
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  // Can be omitted - defaults to true
+  ssr: true,
+  prerender: ["/", "/blog", "/blog/popular-post"],
+} satisfies Config;
+```
+
+#### Data Loading and Pre-rendering
+
+There is no extra application API for pre-rendering. Routes being pre-rendered use the same route `loader` functions as server rendering:
+
+```tsx
+export async function loader({ request, params }) {
+  let post = await getPost(params.slug);
+  return post;
+}
+
+export function Post({ loaderData }) {
+  return <div>{loaderData.title}</div>;
+}
+```
+
+Instead of a request coming to your route on a deployed server, the build creates a `new Request()` and runs it through your app just like a server would.
+
+When server rendering, requests to paths that have not been pre-rendered will be server rendered as usual.
+
+#### Static File Output
+
+The rendered result will be written out to your `build/client` directory. You'll notice two files for each path:
+
+- `[url].html` HTML file for initial document requests
+- `[url].data` file for client side navigation browser requests
+
+The output of your build will indicate what files were pre-rendered:
+
+```sh
+> react-router build
+vite v5.2.11 building for production...
+...
+vite v5.2.11 building SSR bundle for production...
+...
+Prerender: Generated build/client/index.html
+Prerender: Generated build/client/blog.data
+Prerender: Generated build/client/blog/index.html
+Prerender: Generated build/client/blog/my-first-post.data
+Prerender: Generated build/client/blog/my-first-post/index.html
+...
+```
+
+During development, pre-rendering doesn't save the rendered results to the public directory, this only happens for `react-router build`.
+
+### Pre-rendering with `ssr:false`
+
+The above examples assume you are deploying a runtime server but are pre-rendering some static pages to avoid hitting the server, resulting in faster loads.
+
+To disable runtime SSR and configure pre-rendering to be served from a static file server, you can set the `ssr:false` config flag:
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: false, // disable runtime server rendering
+  prerender: true, // pre-render all static routes
+} satisfies Config;
+```
+
+If you specify `ssr:false` without a `prerender` config, React Router refers to that as [SPA Mode](./spa). In SPA Mode, we render a single HTML file that is capable of hydrating for _any_ of your application paths. It can do this because it only renders the `root` route into the HTML file and then determines which child routes to load based on the browser URL during hydration. This means you can use a `loader` on the root route, but not on any other routes because we don't know which routes to load until hydration in the browser.
+
+If you want to pre-render paths with `ssr:false`, those matched routes _can_ have loaders because we'll pre-render all of the matched routes for those paths, not just the root. You cannot include `actions` or `headers` functions in any routes when `ssr:false` is set because there will be no runtime server to run them on.
+
+#### Pre-rendering with a SPA Fallback
+
+If you want `ssr:false` but don't want to pre-render _all_ of your routes - that's fine too! You may have some paths where you need the performance/SEO benefits of pre-rendering, but other pages where a SPA would be fine.
+
+You can do this using the combination of config options as well - just limit your `prerender` config to the paths that you want to pre-render and React Router will also output a "SPA Fallback" HTML file that can be served to hydrate any other paths (using the same approach as [SPA Mode](./spa)).
+
+This will be written to one of the following paths:
+
+- `build/client/index.html` - If the `/` path is not pre-rendered
+- `build/client/__spa-fallback.html` - If the `/` path is pre-rendered
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: false,
+
+  // SPA fallback will be written to build/client/index.html
+  prerender: ["/about-us"],
+
+  // SPA fallback will be written to build/client/__spa-fallback.html
+  prerender: ["/", "/about-us"],
+} satisfies Config;
+```
+
+You can configure your deployment server to serve this file for any path that otherwise would 404. Some hosts do this by default, but others don't. As an example, a host may support a `_redirects` file to do this:
+
+```
+# If you did not pre-render the `/` route
+/*    /index.html   200
+
+# If you pre-rendered the `/` route
+/*    /__spa-fallback.html   200
+```
+
+If you're getting 404s at valid routes for your app, it's likely you need to configure your host.
+
+Here's another example of how you can do this with the [`sirv-cli`](https://www.npmjs.com/package/sirv-cli#user-content-single-page-applications) tool:
+
+```sh
+# If you did not pre-render the `/` route
+sirv-cli build/client --single index.html
+
+# If you pre-rendered the `/` route
+sirv-cli build/client --single __spa-fallback.html
+```
+
+#### Invalid Exports
+
+When pre-rendering with `ssr:false`, React Router will error at build time if you have invalid exports to help prevent some mistakes that can be easily overlooked.
+
+- `headers`/`action` functions are prohibited in all routes because there will be no runtime server on which to run them
+- When using `ssr:false` without a `prerender` config (SPA Mode), a `loader` is permitted on the root route only
+- When using `ssr:false` with a `prerender` config, a `loader` is permitted on any route matched by a `prerender` path
+  - If you are using a `loader` on a pre-rendered route that has child routes, you will need to make sure the parent `loaderData` can be determined at run-time properly by either:
+    - Pre-rendering all child routes so that the parent `loader` can be called at build-time for each child route path and rendered into a `.data` file, or
+    - Use a `clientLoader` on the parent that can be called at run-time for non-pre-rendered child paths

package/docs/how-to/presets.md

@@ -0,0 +1,103 @@
+---
+title: Presets
+---
+
+# Presets
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+The [React Router config][react-router-config] supports a `presets` option to ease integration with other tools and hosting providers.
+
+[Presets][preset-type] can only do two things:
+
+- Configure React Router config options on your behalf
+- Validate the resolved config
+
+The config returned by each preset is merged in the order the presets were defined. Any config directly specified in your React Router config will be merged last. This means that your config will always take precedence over any presets.
+
+## Defining preset config
+
+As a basic example, let's create a preset that configures a [server bundles function][server-bundles]:
+
+```ts filename=my-cool-preset.ts
+import type { Preset } from "@react-router/dev/config";
+
+export function myCoolPreset(): Preset {
+  return {
+    name: "my-cool-preset",
+    reactRouterConfig: () => ({
+      serverBundles: ({ branch }) => {
+        const isAuthenticatedRoute = branch.some((route) =>
+          route.id.split("/").includes("_authenticated"),
+        );
+
+        return isAuthenticatedRoute
+          ? "authenticated"
+          : "unauthenticated";
+      },
+    }),
+  };
+}
+```
+
+## Validating config
+
+Keep in mind that other presets and user config can still override the values returned from your preset.
+
+In our example preset, the `serverBundles` function could be overridden with a different, conflicting implementation. If we want to validate that the final resolved config contains the `serverBundles` function from our preset, we can use the `reactRouterConfigResolved` hook:
+
+```ts filename=my-cool-preset.ts lines=[22-27]
+import type {
+  Preset,
+  ServerBundlesFunction,
+} from "@react-router/dev/config";
+
+const serverBundles: ServerBundlesFunction = ({
+  branch,
+}) => {
+  const isAuthenticatedRoute = branch.some((route) =>
+    route.id.split("/").includes("_authenticated"),
+  );
+
+  return isAuthenticatedRoute
+    ? "authenticated"
+    : "unauthenticated";
+};
+
+export function myCoolPreset(): Preset {
+  return {
+    name: "my-cool-preset",
+    reactRouterConfig: () => ({ serverBundles }),
+    reactRouterConfigResolved: ({ reactRouterConfig }) => {
+      if (
+        reactRouterConfig.serverBundles !== serverBundles
+      ) {
+        throw new Error("`serverBundles` was overridden!");
+      }
+    },
+  };
+}
+```
+
+The `reactRouterConfigResolved` hook should only be used when it would be an error to merge or override your preset's config.
+
+## Using a preset
+
+Presets are designed to be published to npm and used within your React Router config.
+
+```ts filename=react-router.config.ts lines=[6]
+import type { Config } from "@react-router/dev/config";
+import { myCoolPreset } from "react-router-preset-cool";
+
+export default {
+  // ...
+  presets: [myCoolPreset()],
+} satisfies Config;
+```
+
+[react-router-config]: https://api.reactrouter.com/v7/types/_react-router_dev.config.Config.html
+[preset-type]: https://api.reactrouter.com/v7/types/_react-router_dev.config.Preset.html
+[server-bundles]: ./server-bundles