react-router 7.16.0 → 7.17.0

package/dist/production/index.mjs

@@ -1,5 +1,5 @@
 /**
- * react-router v7.16.0
+ * react-router v7.17.0
  *
  * Copyright (c) Remix Software Inc.
  *
@@ -28,7 +28,7 @@ import {
   isSession,
   routeRSCServerRequest,
   setDevServerHooks
-} from "./chunk-NALGHHKE.mjs";
+} from "./chunk-5TQZEVD5.mjs";
 import {
   Action,
   Await,
@@ -142,7 +142,7 @@ import {
   withComponentProps,
   withErrorBoundaryProps,
   withHydrateFallbackProps
-} from "./chunk-Q65P7S7Y.mjs";
+} from "./chunk-OSYEOCBT.mjs";
 export {
   Await,
   BrowserRouter,

package/dist/production/lib/types/internal.js

@@ -1,5 +1,5 @@
 "use strict";/**
- * react-router v7.16.0
+ * react-router v7.17.0
  *
  * Copyright (c) Remix Software Inc.
  *

package/dist/production/lib/types/internal.mjs

@@ -1,5 +1,5 @@
 /**
- * react-router v7.16.0
+ * react-router v7.17.0
  *
  * Copyright (c) Remix Software Inc.
  *

package/docs/explanation/backend-for-frontend.md

@@ -0,0 +1,50 @@
+---
+title: Backend For Frontend
+---
+
+# Backend For Frontend
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+While React Router can serve as your fullstack application, it also fits perfectly into the "Backend for Frontend" architecture.
+
+The BFF strategy employs a web server with a job scoped to serving the frontend web app and connecting it to the services it needs: your database, mailer, job queues, existing backend APIs (REST, GraphQL), etc. Instead of your UI integrating directly from the browser to these services, it connects to the BFF, and the BFF connects to your services.
+
+Mature apps already have a lot of backend application code in Ruby, Elixir, PHP, etc., and there's no reason to justify migrating it all to a server-side JavaScript runtime just to get the benefits of React Router. Instead, you can use your React Router app as a backend for your frontend.
+
+You can use `fetch` right from your loaders and actions to your backend.
+
+```tsx lines=[7,13,17]
+import escapeHtml from "escape-html";
+
+export async function loader() {
+  const apiUrl = "https://api.example.com/some-data.json";
+  const res = await fetch(apiUrl, {
+    headers: {
+      Authorization: `Bearer ${process.env.API_TOKEN}`,
+    },
+  });
+
+  const data = await res.json();
+
+  const prunedData = data.map((record) => {
+    return {
+      id: record.id,
+      title: record.title,
+      formattedBody: escapeHtml(record.content),
+    };
+  });
+  return { prunedData };
+}
+```
+
+There are several benefits of this approach vs. fetching directly from the browser. The highlighted lines above show how you can:
+
+1. Simplify third-party integrations and keep tokens and secrets out of client bundles
+2. Prune the data down to send less kB over the network, speeding up your app significantly
+3. Move a lot of code from browser bundles to the server, like `escapeHtml`, which speeds up your app. Additionally, moving code to the server usually makes your code easier to maintain since server-side code doesn't have to worry about UI states for async operations
+
+Again, React Router can be used as your only server by talking directly to the database and other services with server-side JavaScript APIs, but it also works perfectly as a backend for your frontend. Go ahead and keep your existing API server for application logic and let React Router connect the UI to it.

package/docs/explanation/code-splitting.md

@@ -0,0 +1,61 @@
+---
+title: Automatic Code Splitting
+---
+
+# Automatic Code Splitting
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+When using React Router's framework features, your application is automatically code split to improve the performance of initial load times when users visit your application.
+
+## Code Splitting by Route
+
+Consider this simple route config:
+
+```tsx filename=app/routes.ts
+import {
+  type RouteConfig,
+  route,
+} from "@react-router/dev/routes";
+
+export default [
+  route("/contact", "./contact.tsx"),
+  route("/about", "./about.tsx"),
+] satisfies RouteConfig;
+```
+
+Instead of bundling all routes into a single giant build, the modules referenced (`contact.tsx` and `about.tsx`) become entry points to the bundler.
+
+Because these entry points are coupled to URL segments, React Router knows just from a URL which bundles are needed in the browser, and more importantly, which are not.
+
+If the user visits `"/about"` then the bundles for `about.tsx` will be loaded but not `contact.tsx`. This drastically reduces the JavaScript footprint for initial page loads and speeds up your application.
+
+## Removal of Server Code
+
+Any server-only [Route Module APIs][route-module] will be removed from the bundles. Consider this route module:
+
+```tsx
+export async function loader() {
+  return { message: "hello" };
+}
+
+export async function action() {
+  console.log(Date.now());
+  return { ok: true };
+}
+
+export async function headers() {
+  return { "Cache-Control": "max-age=300" };
+}
+
+export default function Component({ loaderData }) {
+  return <div>{loaderData.message}</div>;
+}
+```
+
+After building for the browser, only the `Component` will still be in the bundle, so you can use server-only code in the other module exports.
+
+[route-module]: ../start/framework/route-module

package/docs/explanation/concurrency.md

@@ -0,0 +1,135 @@
+---
+title: Network Concurrency Management
+---
+
+# Network Concurrency Management
+
+[MODES: framework, data]
+
+<br/>
+<br/>
+
+When building web applications, managing network requests can be a daunting task. The challenges of ensuring up-to-date data and handling simultaneous requests often lead to complex logic in the application to deal with interruptions and race conditions. React Router simplifies this process by automating network management while mirroring and expanding upon the intuitive behavior of web browsers.
+
+To help understand how React Router handles concurrency, it's important to remember that after `form` submissions, React Router will fetch fresh data from the `loader`s. This is called revalidation.
+
+## Natural Alignment with Browser Behavior
+
+React Router's handling of network concurrency is heavily inspired by the default behavior of web browsers when processing documents.
+
+### Link Navigation
+
+**Browser Behavior**: When you click on a link in a browser and then click on another before the page transition completes, the browser prioritizes the most recent `action`. It cancels the initial request, focusing solely on the latest link clicked.
+
+**React Router Behavior**: React Router manages client-side navigation the same way. When a link is clicked within a React Router application, it initiates fetch requests for each `loader` tied to the target URL. If another navigation interrupts the initial navigation, React Router cancels the previous fetch requests, ensuring that only the latest requests proceed.
+
+### Form Submission
+
+**Browser Behavior**: If you initiate a form submission in a browser and then quickly submit another form again, the browser disregards the first submission, processing only the latest one.
+
+**React Router Behavior**: React Router mimics this behavior when working with forms. If a form is submitted and another submission occurs before the first completes, React Router cancels the original fetch requests. It then waits for the latest submission to complete before triggering page revalidation again.
+
+## Concurrent Submissions and Revalidation
+
+While standard browsers are limited to one request at a time for navigations and form submissions, React Router elevates this behavior. Unlike navigation, with [`useFetcher`][use_fetcher] multiple requests can be in flight simultaneously.
+
+React Router is designed to handle multiple form submissions to server `action`s and concurrent revalidation requests efficiently. It ensures that as soon as new data is available, the state is updated promptly. However, React Router also safeguards against potential pitfalls by refraining from committing stale data when other `action`s introduce race conditions.
+
+For instance, if three form submissions are in progress, and one completes, React Router updates the UI with that data immediately without waiting for the other two so that the UI remains responsive and dynamic. As the remaining submissions finalize, React Router continues to update the UI, ensuring that the most recent data is displayed.
+
+Using this key:
+
+- `|`: Submission begins
+- ✓: Action complete, data revalidation begins
+- ✅: Revalidated data is committed to the UI
+- ❌: Request cancelled
+
+We can visualize this scenario in the following diagram:
+
+```text
+submission 1: |----✓-----✅
+submission 2:    |-----✓-----✅
+submission 3:             |-----✓-----✅
+```
+
+However, if a subsequent submission's revalidation completes before an earlier one, React Router discards the earlier data, ensuring that only the most up-to-date information is reflected in the UI:
+
+```text
+submission 1: |----✓---------❌
+submission 2:    |-----✓-----✅
+submission 3:             |-----✓-----✅
+```
+
+Because the revalidation from submission (2) started later and landed earlier than submission (1), the requests from submission (1) are canceled and only the data from submission (2) is committed to the UI. It was requested later, so it's more likely to contain the updated values from both (1) and (2).
+
+## Potential for Stale Data
+
+It's unlikely your users will ever experience this, but there are still chances for the user to see stale data in very rare conditions with inconsistent infrastructure. Even though React Router cancels requests for stale data, they will still end up making it to the server. Canceling a request in the browser simply releases browser resources for that request; it can't "catch up" and stop it from getting to the server. In extremely rare conditions, a canceled request may change data after the interrupting `action`'s revalidation lands. Consider this diagram:
+
+```text
+     👇 interruption with new submission
+|----❌----------------------✓
+       |-------✓-----✅
+                             👆
+                  initial request reaches the server
+                  after the interrupting submission
+                  has completed revalidation
+```
+
+The user is now looking at different data than what is on the server. Note that this problem is both extremely rare and exists with default browser behavior, too. The chance of the initial request reaching the server later than both the submission and revalidation of the second is unexpected on any network and server infrastructure. If this is a concern with your infrastructure, you can send timestamps with your form submissions and write server logic to ignore stale submissions.
+
+## Example
+
+In UI components like comboboxes, each keystroke can trigger a network request. Managing such rapid, consecutive requests can be tricky, especially when ensuring that the displayed results match the most recent query. However, with React Router, this challenge is automatically handled, ensuring that users see the correct results without developers having to micromanage the network.
+
+```tsx filename=app/pages/city-search.tsx
+export async function loader({ request }) {
+  const { searchParams } = new URL(request.url);
+  const cities = await searchCities(searchParams.get("q"));
+  return cities;
+}
+
+export function CitySearchCombobox() {
+  const fetcher = useFetcher<typeof loader>();
+
+  return (
+    <fetcher.Form action="/city-search">
+      <Combobox aria-label="Cities">
+        <ComboboxInput
+          name="q"
+          onChange={(event) =>
+            // submit the form onChange to get the list of cities
+            fetcher.submit(event.target.form)
+          }
+        />
+
+        {/* render with the loader's data */}
+        {fetcher.data ? (
+          <ComboboxPopover className="shadow-popup">
+            {fetcher.data.length > 0 ? (
+              <ComboboxList>
+                {fetcher.data.map((city) => (
+                  <ComboboxOption
+                    key={city.id}
+                    value={city.name}
+                  />
+                ))}
+              </ComboboxList>
+            ) : (
+              <span>No results found</span>
+            )}
+          </ComboboxPopover>
+        ) : null}
+      </Combobox>
+    </fetcher.Form>
+  );
+}
+```
+
+All the application needs to know is how to query the data and how to render it. React Router handles the network.
+
+## Conclusion
+
+React Router offers developers an intuitive, browser-based approach to managing network requests. By mirroring browser behaviors and enhancing them where needed, it simplifies the complexities of concurrency, revalidation, and potential race conditions. Whether you're building a simple webpage or a sophisticated web application, React Router ensures that your user interactions are smooth, reliable, and always up to date.
+
+[use_fetcher]: ../api/hooks/useFetcher

package/docs/explanation/form-vs-fetcher.md

@@ -0,0 +1,292 @@
+---
+title: Form vs. fetcher
+---
+
+# Form vs. fetcher
+
+[MODES: framework, data]
+
+## Overview
+
+Developing in React Router offers a rich set of tools that can sometimes overlap in functionality, creating a sense of ambiguity for newcomers. The key to effective development in React Router is understanding the nuances and appropriate use cases for each tool. This document seeks to provide clarity on when and why to use specific APIs.
+
+## APIs in Focus
+
+- [`<Form>`][form-component]
+- [`useFetcher`][use-fetcher]
+- [`useNavigation`][use-navigation]
+
+Understanding the distinctions and intersections of these APIs is vital for efficient and effective React Router development.
+
+## URL Considerations
+
+The primary criterion when choosing among these tools is whether you want the URL to change or not:
+
+- **URL Change Desired**: When navigating or transitioning between pages, or after certain actions like creating or deleting records. This ensures that the user's browser history accurately reflects their journey through your application.
+  - **Expected Behavior**: In many cases, when users hit the back button, they should be taken to the previous page. Other times the history entry may be replaced but the URL change is important nonetheless.
+
+- **No URL Change Desired**: For actions that don't significantly change the context or primary content of the current view. This might include updating individual fields or minor data manipulations that don't warrant a new URL or page reload. This also applies to loading data with fetchers for things like popovers, combo boxes, etc.
+
+### When the URL Should Change
+
+These actions typically reflect significant changes to the user's context or state:
+
+- **Creating a New Record**: After creating a new record, it's common to redirect users to a page dedicated to that new record, where they can view or further modify it.
+
+- **Deleting a Record**: If a user is on a page dedicated to a specific record and decides to delete it, the logical next step is to redirect them to a general page, such as a list of all records.
+
+For these cases, developers should consider using a combination of [`<Form>`][form-component] and [`useNavigation`][use-navigation]. These tools can be coordinated to handle form submission, invoke specific actions, retrieve action-related data through component props, and manage navigation respectively.
+
+### When the URL Shouldn't Change
+
+These actions are generally more subtle and don't require a context switch for the user:
+
+- **Updating a Single Field**: Maybe a user wants to change the name of an item in a list or update a specific property of a record. This action is minor and doesn't necessitate a new page or URL.
+
+- **Deleting a Record from a List**: In a list view, if a user deletes an item, they likely expect to remain on the list view, with that item no longer in the list.
+
+- **Creating a Record in a List View**: When adding a new item to a list, it often makes sense for the user to remain in that context, seeing their new item added to the list without a full page transition.
+
+- **Loading Data for a Popover or Combobox**: When loading data for a popover or combobox, the user's context remains unchanged. The data is loaded in the background and displayed in a small, self-contained UI element.
+
+For such actions, [`useFetcher`][use-fetcher] is the go-to API. It's versatile, combining functionalities of these APIs, and is perfectly suited for tasks where the URL should remain unchanged.
+
+## API Comparison
+
+As you can see, the two sets of APIs have a lot of similarities:
+
+| Navigation/URL API            | Fetcher API          |
+| ----------------------------- | -------------------- |
+| `<Form>`                      | `<fetcher.Form>`     |
+| `actionData` (component prop) | `fetcher.data`       |
+| `navigation.state`            | `fetcher.state`      |
+| `navigation.formAction`       | `fetcher.formAction` |
+| `navigation.formData`         | `fetcher.formData`   |
+
+## Examples
+
+### Creating a New Record
+
+```tsx filename=app/pages/new-recipe.tsx lines=[16,23-24,29]
+import {
+  Form,
+  redirect,
+  useNavigation,
+} from "react-router";
+import type { Route } from "./+types/new-recipe";
+
+export async function action({
+  request,
+}: Route.ActionArgs) {
+  const formData = await request.formData();
+  const errors = await validateRecipeFormData(formData);
+  if (errors) {
+    return { errors };
+  }
+  const recipe = await db.recipes.create(formData);
+  return redirect(`/recipes/${recipe.id}`);
+}
+
+export function NewRecipe({
+  actionData,
+}: Route.ComponentProps) {
+  const { errors } = actionData || {};
+  const navigation = useNavigation();
+  const isSubmitting =
+    navigation.formAction === "/recipes/new";
+
+  return (
+    <Form method="post">
+      <label>
+        Title: <input name="title" />
+        {errors?.title ? <span>{errors.title}</span> : null}
+      </label>
+      <label>
+        Ingredients: <textarea name="ingredients" />
+        {errors?.ingredients ? (
+          <span>{errors.ingredients}</span>
+        ) : null}
+      </label>
+      <label>
+        Directions: <textarea name="directions" />
+        {errors?.directions ? (
+          <span>{errors.directions}</span>
+        ) : null}
+      </label>
+      <button type="submit">
+        {isSubmitting ? "Saving..." : "Create Recipe"}
+      </button>
+    </Form>
+  );
+}
+```
+
+The example leverages [`<Form>`][form-component], component props, and [`useNavigation`][use-navigation] to facilitate an intuitive record creation process.
+
+Using `<Form>` ensures direct and logical navigation. After creating a record, the user is naturally guided to the new recipe's unique URL, reinforcing the outcome of their action.
+
+The component props bridge server and client, providing immediate feedback on submission issues. This quick response enables users to rectify any errors without hindrance.
+
+Lastly, `useNavigation` dynamically reflects the form's submission state. This subtle UI change, like toggling the button's label, assures users that their actions are being processed.
+
+Combined, these APIs offer a balanced blend of structured navigation and feedback.
+
+### Updating a Record
+
+Now consider we're looking at a list of recipes that have delete buttons on each item. When a user clicks the delete button, we want to delete the recipe from the database and remove it from the list without navigating away from the list.
+
+First, consider the basic route setup to get a list of recipes on the page:
+
+```tsx filename=app/pages/recipes.tsx
+import type { Route } from "./+types/recipes";
+
+export async function loader({
+  request,
+}: Route.LoaderArgs) {
+  return {
+    recipes: await db.recipes.findAll({ limit: 30 }),
+  };
+}
+
+export default function Recipes({
+  loaderData,
+}: Route.ComponentProps) {
+  const { recipes } = loaderData;
+  return (
+    <ul>
+      {recipes.map((recipe) => (
+        <RecipeListItem key={recipe.id} recipe={recipe} />
+      ))}
+    </ul>
+  );
+}
+```
+
+Now we'll look at the action that deletes a recipe and the component that renders each recipe in the list.
+
+```tsx filename=app/pages/recipes.tsx lines=[10,21,27]
+import { useFetcher } from "react-router";
+import type { Recipe } from "./recipe.server";
+import type { Route } from "./+types/recipes";
+
+export async function action({
+  request,
+}: Route.ActionArgs) {
+  const formData = await request.formData();
+  const id = formData.get("id");
+  await db.recipes.delete(id);
+  return { ok: true };
+}
+
+export default function Recipes() {
+  return (
+    // ...
+    // doesn't matter, somewhere it's using <RecipeListItem />
+  )
+}
+
+function RecipeListItem({ recipe }: { recipe: Recipe }) {
+  const fetcher = useFetcher();
+  const isDeleting = fetcher.state !== "idle";
+
+  return (
+    <li>
+      <h2>{recipe.title}</h2>
+      <fetcher.Form method="post">
+        <input type="hidden" name="id" value={recipe.id} />
+        <button disabled={isDeleting} type="submit">
+          {isDeleting ? "Deleting..." : "Delete"}
+        </button>
+      </fetcher.Form>
+    </li>
+  );
+}
+```
+
+Using [`useFetcher`][use-fetcher] in this scenario works perfectly. Instead of navigating away or refreshing the entire page, we want in-place updates. When a user deletes a recipe, the `action` is called and the fetcher manages the corresponding state transitions.
+
+The key advantage here is the maintenance of context. The user stays on the list when the deletion completes. The fetcher's state management capabilities are leveraged to give real-time feedback: it toggles between `"Deleting..."` and `"Delete"`, providing a clear indication of the ongoing process.
+
+Furthermore, with each `fetcher` having the autonomy to manage its own state, operations on individual list items become independent, ensuring that actions on one item don't affect the others (though revalidation of the page data is a shared concern covered in [Network Concurrency Management][network-concurrency-management]).
+
+In essence, `useFetcher` offers a seamless mechanism for actions that don't necessitate a change in the URL or navigation, enhancing the user experience by providing real-time feedback and context preservation.
+
+### Mark Article as Read
+
+Imagine you want to mark that an article has been read by the current user, after they've been on the page for a while and scrolled to the bottom. You could make a hook that looks something like this:
+
+```tsx
+import { useFetcher } from "react-router";
+
+function useMarkAsRead({ articleId, userId }) {
+  const marker = useFetcher();
+
+  useSpentSomeTimeHereAndScrolledToTheBottom(() => {
+    marker.submit(
+      { userId },
+      {
+        action: `/article/${articleId}/mark-as-read`,
+        method: "post",
+      },
+    );
+  });
+}
+```
+
+### User Avatar Details Popup
+
+Anytime you show the user avatar, you could put a hover effect that fetches data from a loader and displays it in a popup.
+
+```tsx filename=app/pages/user-details.tsx
+import { useState, useEffect } from "react";
+import { useFetcher } from "react-router";
+import type { Route } from "./+types/user-details";
+
+export async function loader({ params }: Route.LoaderArgs) {
+  return await fakeDb.user.find({
+    where: { id: params.id },
+  });
+}
+
+type LoaderData = Route.ComponentProps["loaderData"];
+
+function UserAvatar({ partialUser }) {
+  const userDetails = useFetcher<LoaderData>();
+  const [showDetails, setShowDetails] = useState(false);
+
+  useEffect(() => {
+    if (
+      showDetails &&
+      userDetails.state === "idle" &&
+      !userDetails.data
+    ) {
+      userDetails.load(`/user-details/${partialUser.id}`);
+    }
+  }, [showDetails, userDetails, partialUser.id]);
+
+  return (
+    <div
+      onMouseEnter={() => setShowDetails(true)}
+      onMouseLeave={() => setShowDetails(false)}
+    >
+      <img src={partialUser.profileImageUrl} />
+      {showDetails ? (
+        userDetails.state === "idle" && userDetails.data ? (
+          <UserPopup user={userDetails.data} />
+        ) : (
+          <UserPopupLoading />
+        )
+      ) : null}
+    </div>
+  );
+}
+```
+
+## Conclusion
+
+React Router offers a range of tools to cater to varied developmental needs. While some functionalities might seem to overlap, each tool has been crafted with specific scenarios in mind. By understanding the intricacies and ideal applications of `<Form>`, `useFetcher`, and `useNavigation`, along with how data flows through component props, developers can create more intuitive, responsive, and user-friendly web applications.
+
+[form-component]: ../api/components/Form
+[use-fetcher]: ../api/hooks/useFetcher
+[use-navigation]: ../api/hooks/useNavigation
+[network-concurrency-management]: ./concurrency