react-router 7.16.0 → 8.0.0-pre.0

package/docs/explanation/progressive-enhancement.md

@@ -0,0 +1,150 @@
+---
+title: Progressive Enhancement
+---
+
+# Progressive Enhancement
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+> Progressive enhancement is a strategy in web design that puts emphasis on web content first, allowing everyone to access the basic content and functionality of a web page, whilst users with additional browser features or faster Internet access receive the enhanced version instead.
+>
+> <cite>- [Wikipedia][wikipedia]</cite>
+
+When using React Router with Server-Side Rendering (the default in framework mode), you can automatically leverage the benefits of progressive enhancement.
+
+## Why Progressive Enhancement Matters
+
+Coined in 2003 by Steven Champeon & Nick Finck, the phrase emerged during a time of varied CSS and JavaScript support across different browsers, with many users actually browsing the web with JavaScript disabled.
+
+Today, we are fortunate to develop for a much more consistent web and where the majority of users have JavaScript enabled.
+
+However, we still believe in the core principles of progressive enhancement in React Router. It leads to fast and resilient apps with simple development workflows.
+
+**Performance**: While it's easy to think that only 5% of your users have slow connections, the reality is that 100% of your users have slow connections 5% of the time.
+
+**Resilience**: Everybody has JavaScript disabled until it's loaded.
+
+**Simplicity**: Building your apps in a progressively enhanced way with React Router is actually simpler than building a traditional SPA.
+
+## Performance
+
+Server rendering allows your app to do more things in parallel than a typical [Single Page App (SPA)][spa], making the initial loading experience and subsequent navigations faster.
+
+Typical SPAs send a blank document and only start doing work when JavaScript has loaded:
+
+```
+HTML        |---|
+JavaScript      |---------|
+Data                      |---------------|
+                            page rendered 👆
+```
+
+A React Router app can start doing work the moment the request hits the server and stream the response so that the browser can start downloading JavaScript, other assets, and data in parallel:
+
+```
+               👇 first byte
+HTML        |---|-----------|
+JavaScript      |---------|
+Data        |---------------|
+              page rendered 👆
+```
+
+## Resilience and Accessibility
+
+While your users probably don't browse the web with JavaScript disabled, everybody uses the websites without JavaScript before it finishes loading. React Router embraces progressive enhancement by building on top of HTML, allowing you to build your app in a way that works without JavaScript, and then layer on JavaScript to enhance the experience.
+
+The simplest case is a `<Link to="/account">`. These render an `<a href="/account">` tag that works without JavaScript. When JavaScript loads, React Router will intercept clicks and handle the navigation with client side routing. This gives you more control over the UX instead of just spinning favicons in the browser tab--but it works either way.
+
+Now consider a simple add to cart button:
+
+```tsx
+export function AddToCart({ id }) {
+  return (
+    <Form method="post" action="/add-to-cart">
+      <input type="hidden" name="id" value={id} />
+      <button type="submit">Add To Cart</button>
+    </Form>
+  );
+}
+```
+
+Whether JavaScript has loaded or not doesn't matter, this button will add the product to the cart.
+
+When JavaScript loads, React Router will intercept the form submission and handle it client side. This allows you to add your own pending UI, or other client side behavior.
+
+## Simplicity
+
+When you start to rely on basic features of the web like HTML and URLs, you will find that you reach for client side state and state management much less.
+
+Consider the button from before, with no fundamental change to the code, we can pepper in some client side behavior:
+
+```tsx lines=[1,4,7,10-12,14]
+import { useFetcher } from "react-router";
+
+export function AddToCart({ id }) {
+  const fetcher = useFetcher();
+
+  return (
+    <fetcher.Form method="post" action="/add-to-cart">
+      <input name="id" value={id} />
+      <button type="submit">
+        {fetcher.state === "submitting"
+          ? "Adding..."
+          : "Add To Cart"}
+      </button>
+    </fetcher.Form>
+  );
+}
+```
+
+This feature continues to work the very same as it did before when JavaScript is loading, but once JavaScript loads:
+
+- `useFetcher` no longer causes a navigation like `<Form>` does, so the user can stay on the same page and keep shopping
+- The app code determines the pending UI instead of spinning favicons in the browser
+
+It's not about building it two different ways–once for JavaScript and once without–it's about building it in iterations. Start with the simplest version of the feature and ship it; then iterate to an enhanced user experience.
+
+Not only will the user get a progressively enhanced experience, but the app developer gets to "progressively enhance" the UI without changing the fundamental design of the feature.
+
+Another example where progressive enhancement leads to simplicity is with the URL. When you start with a URL, you don't need to worry about client side state management. You can just use the URL as the source of truth for the UI.
+
+```tsx
+export function SearchBox() {
+  return (
+    <Form method="get" action="/search">
+      <input type="search" name="query" />
+      <SearchIcon />
+    </Form>
+  );
+}
+```
+
+This component doesn't need any state management. It just renders a form that submits to `/search`. When JavaScript loads, React Router will intercept the form submission and handle it client side. Here's the next iteration:
+
+```tsx lines=[1,4-6,11]
+import { useNavigation } from "react-router";
+
+export function SearchBox() {
+  const navigation = useNavigation();
+  const isSearching =
+    navigation.location.pathname === "/search";
+
+  return (
+    <Form method="get" action="/search">
+      <input type="search" name="query" />
+      {isSearching ? <Spinner /> : <SearchIcon />}
+    </Form>
+  );
+}
+```
+
+No fundamental change in architecture, simply a progressive enhancement for both the user and the code.
+
+See also: [State Management][state_management]
+
+[wikipedia]: https://en.wikipedia.org/wiki/Progressive_enhancement
+[spa]: ../how-to/spa
+[state_management]: ./state-management

package/docs/explanation/race-conditions.md

@@ -0,0 +1,88 @@
+---
+title: Race Conditions
+---
+
+# Race Conditions
+
+[MODES: framework, data]
+
+<br/>
+<br/>
+
+While impossible to eliminate every possible race condition in your application, React Router automatically handles the most common race conditions found in web user interfaces.
+
+## Browser Behavior
+
+React Router's handling of network concurrency is heavily inspired by the behavior of web browsers when processing documents.
+
+Consider clicking a link to a new document, and then clicking a different link before the new page has finished loading. The browser will:
+
+1. cancel the first request
+2. immediately process the new navigation
+
+The same behavior applies to form submissions. When a pending form submission is interrupted by a new one, the first is canceled and the new submission is immediately processed.
+
+## React Router Behavior
+
+Like the browser, interrupted navigations with links and form submissions will cancel in flight data requests and immediately process the new event.
+
+Fetchers are a bit more nuanced since they are not singleton events like navigation. Fetchers can't interrupt other fetcher instances, but they can interrupt themselves and the behavior is the same as everything else: cancel the interrupted request and immediately process the new one.
+
+Fetchers do, however, interact with each other when it comes to revalidation. After a fetcher's action request returns to the browser, a revalidation for all page data is sent. This means multiple revalidation requests can be in-flight at the same time. React Router will commit all "fresh" revalidation responses and cancel any stale requests. A stale request is any request that started _earlier_ than one that has returned.
+
+This management of the network prevents the most common UI bugs caused by network race conditions.
+
+Since networks are unpredictable, and your server still processes these cancelled requests, your backend may still experience race conditions and have potential data integrity issues. These risks are the same risks as using default browser behavior with plain HTML `<forms>`, which we consider to be low, and outside the scope of React Router.
+
+## Practical Benefits
+
+Consider building a type-ahead combobox. As the user types, you send a request to the server. As they type each new character you send a new request. It's important to not show the user results for a value that's not in the text field anymore.
+
+When using a fetcher, this is automatically managed for you. Consider this pseudo-code:
+
+```tsx
+// route("/city-search", "./search-cities.ts")
+export async function loader({ request }) {
+  const { searchParams } = new URL(request.url);
+  return searchCities(searchParams.get("q"));
+}
+```
+
+```tsx
+export function CitySearchCombobox() {
+  const fetcher = useFetcher();
+
+  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)
+          }
+        />
+
+        {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>
+  );
+}
+```
+
+Calls to `fetcher.submit` will cancel pending requests on that fetcher automatically. This ensures you never show the user results for a request for a different input value.

package/docs/explanation/react-transitions.md

@@ -0,0 +1,160 @@
+---
+title: React Transitions
+---
+
+# React Transitions
+
+[MODES: framework, data, declarative]
+
+<br/>
+<br/>
+
+[React 18][react-18] introduced the concept of "transitions" which allow you to differentiate urgent from non-urgent UI updates. To learn more about React Transitions and "concurrent rendering" Please refer to React's official documentation:
+
+- [What is Concurrent React][concurrent]
+- [Transitions][transitions]
+- [`React.useTransition`][use-transition]
+- [`React.startTransition`][start-transition]
+
+[React 19][react-19] enhances the async/concurrent landscape by introducing [Actions][actions] and support for using async functions in Transitions. With the support for async Transitions, a new [`React.useOptimistic`][use-optimistic-blog] [hook][use-optimistic] was also introduced that allows you to surface state updates during a Transition to show users instant feedback.
+
+## Transitions in React Router
+
+The introduction of Transitions in React makes the story of how React Router manages your navigations and router state a bit more complicated. These are powerful APIs but they don't come without some nuance and added complexity. We aim to make React Router work seamlessly with the new React features, but in some cases there may exist some tension between the new React ways to do things and some patterns you are already using in your React Router apps (i.e., pending states, optimistic UI).
+
+To ensure a smooth adoption story, we've introduced changes related to Transitions behind an opt-in `useTransitions` flag so that you can upgrade in a non-breaking fashion.
+
+### Current Behavior
+
+We first leveraged `React.startTransition` to make React Router more Suspense-friendly in React Router [6.13.0][rr-6-13-0] via the `future.v7_startTransition` flag. In v7, that became the default behavior and all router state updates are currently wrapped in `React.startTransition`.
+
+This default behavior has 2 potential issues that `useTransitions` is designed to solve:
+
+- There are some valid use cases where you _don't_ want your updates wrapped in `startTransition`
+  - One specific issue is that `React.useSyncExternalStore` updates can't be Transitions ([^1][uses-transition-issue], [^2][uses-transition-tweet]). `useSyncExternalStore` forces a sync update, which means fallbacks can be shown in update transitions that would otherwise avoid showing the fallback.
+  - React Router has a `flushSync` option on navigations to use [`React.flushSync`][flush-sync] for state updates instead, but that's not always a proper solution
+- React 19 has added a new `startTransition(() => Promise))` API as well as a new `useOptimistic` hook to surface updates during Transitions
+  - Without some updates to React Router, `startTransition(() => navigate(path))` doesn't work as you might expect, because we are not using `useOptimistic` internally so router state updates don't surface during the navigation, which breaks hooks like `useNavigation`
+
+To provide a solution to both of the above issues, we're introducing a new `useTransitions` prop to the router components that will let you opt-out of using `startTransition` for router state updates (solving the first issue), or opt-into a more enhanced usage of `startTransition` + `useOptimistic` (solving the second issue). Because the current behavior is a bit incomplete with the new React 19 APIs, we plan to make the opt-in behavior the default in React Router v8, but we will likely retain the opt-out flag for use cases such as `useSyncExternalStore`.
+
+### Opt-out via `useTransitions=false`
+
+If your application is not "Transition-friendly" due to the usage of `useSyncExternalStore` (or other reasons), then you can opt-out via the prop:
+
+```tsx
+// Framework Mode (entry.client.tsx)
+<HydratedRouter useTransitions={false} />
+
+// Data Mode
+<RouterProvider useTransitions={false} />
+
+// Declarative Mode
+<BrowserRouter useTransitions={false} />
+```
+
+This will stop the router from wrapping internal state updates in `startTransition`.
+
+### Opt-in via `useTransitions=true`
+
+<docs-info>Opting into this feature in Framework or Data Mode requires that you are using React 19 because it needs access to [`React.useOptimistic`][use-optimistic]</docs-info>
+
+If you want to make your application play nicely with all of the new React 19 features that rely on concurrent mode and Transitions, then you can opt-in via the new prop:
+
+```tsx
+// Framework Mode (entry.client.tsx)
+<HydratedRouter useTransitions />
+
+// Data Mode
+<RouterProvider useTransitions />
+
+// Declarative Mode
+<BrowserRouter useTransitions />
+```
+
+With this flag enabled:
+
+- All internal state updates are wrapped in `React.startTransition` (current behavior without the flag)
+- All `<Link>`/`<Form>` navigations will be wrapped in `React.startTransition`, using the promise returned by `useNavigate`/`useSubmit` so that the Transition lasts for the duration of the navigation
+  - `useNavigate`/`useSubmit` do not automatically wrap in `React.startTransition`, so you can opt-out of a Transition-enabled navigation by using those directly
+- In Framework/Data modes, a subset of the router state updates during a navigation will be surfaced to the UI via `useOptimistic`
+  - State related to the _ongoing_ navigation and all fetcher information will be surfaced:
+    - `state.navigation` for `useNavigation()`
+    - `state.revalidation` for `useRevalidator()`
+    - `state.actionData` for `useActionData()`
+    - `state.fetchers` for `useFetcher()` and `useFetchers()`
+  - State related to the _current_ location will not be surfaced:
+    - `state.location` for `useLocation`
+    - `state.matches` for `useMatches()`,
+    - `state.loaderData` for `useLoaderData()`
+    - `state.errors` for `useRouteError()`
+    - etc.
+
+Enabling this flag means that you can now have fully-Transition-enabled navigations that play nicely with any other ongoing Transition-enabled aspects of your application.
+
+The only APIs that are automatically wrapped in an async Transition are `<Link>` and `<Form>`. For everything else, you need to wrap the operation in `startTransition` yourself.
+
+```tsx
+// Automatically Transition-enabled
+<Link to="/path" />
+<Form method="post" action="/path" />
+
+// Manually Transition-enabled
+startTransition(() => navigate("/path"));
+startTransition(() => submit(data, { method: 'post', action: "/path" }));
+startTransition(() => fetcher.load("/path"));
+startTransition(() => fetcher.submit(data, { method: "post", action: "/path" }));
+
+// Not Transition-enabled
+navigate("/path");
+submit(data, { method: 'post', action: "/path" });
+fetcher.load("/path");
+fetcher.submit(data, { method: "post", action: "/path" });
+```
+
+**Important:** You must always `return` or `await` the `navigate` promise inside `startTransition` so that the Transition encompasses the full duration of the navigation. If you forget to `return` or `await` the promise, the Transition will end prematurely and things won't work as expected.
+
+```tsx
+// ✅ Returned promise
+startTransition(() => navigate("/path"));
+startTransition(() => {
+  setOptimistic(something);
+  return navigate("/path"));
+});
+
+// ✅ Awaited promise
+startTransition(async () => {
+  setOptimistic(something);
+  await navigate("/path"));
+});
+
+// ❌ Non-returned promise
+startTransition(() => {
+  setOptimistic(something);
+  navigate("/path"));
+});
+
+// ❌ Non-Awaited promise
+startTransition(async () => {
+  setOptimistic(something);
+  navigate("/path"));
+});
+```
+
+#### `popstate` navigations
+
+There is currently a bug with optimistic states and `popstate`. If you need to read the current route during a back navigation, which cannot complete synchronously (e.g. Suspends on uncached data), you can set the optimistic state before navigating back or defer the optimistic update in a timer or microtask.
+
+[react-18]: https://react.dev/blog/2022/03/29/react-v18
+[concurrent]: https://react.dev/blog/2022/03/29/react-v18#what-is-concurrent-react
+[transitions]: https://react.dev/blog/2022/03/29/react-v18#new-feature-transitions
+[use-transition]: https://react.dev/reference/react/useTransition#reference
+[start-transition]: https://react.dev/reference/react/startTransition
+[react-19]: https://react.dev/blog/2024/12/05/react-19
+[actions]: https://react.dev/blog/2024/12/05/react-19#actions
+[use-optimistic-blog]: https://react.dev/blog/2024/12/05/react-19#new-hook-optimistic-updates
+[use-optimistic]: https://react.dev/reference/react/useOptimistic
+[flush-sync]: https://react.dev/reference/react-dom/flushSync
+[rr-6-13-0]: https://github.com/remix-run/react-router/blob/main/CHANGELOG.md#v6130
+[uses-transition-issue]: https://github.com/facebook/react/issues/26382
+[uses-transition-tweet]: https://x.com/rickhanlonii/status/1683636856808775682

package/docs/explanation/route-matching.md

@@ -0,0 +1,7 @@
+---
+title: Route Matching
+hidden: true
+# want to explain how the matching algorithm works with any potential gotchas
+---
+
+# Route Matching

package/docs/explanation/server-client-execution.md

@@ -0,0 +1,4 @@
+---
+title: Server vs. Client Code Execution
+hidden: true
+---