react-router 8.4.0 → 8.5.1

package/docs/how-to/view-transitions.md

@@ -4,16 +4,75 @@ title: View Transitions
 
 # View Transitions
 
-[MODES: framework, data]
+[MODES: framework, data, declarative]
 
-<br/>
-<br/>
+Use React's [`<ViewTransition>`][react-view-transition] component to animate client-side navigations. This requires React and React DOM 19.3 or later.
 
-Enable smooth animations between page transitions in your React Router applications using the [View Transitions API][view-transitions-api]. This feature allows you to create seamless visual transitions during client-side navigation.
+<docs-warning>
 
-## Basic View Transition
+React Router's `viewTransition` props/options, `useViewTransitionState` hook, and `NavLink`'s `isTransitioning` render prop and `transitioning` class are deprecated in favor of React's `<ViewTransition>` component. The existing APIs continue to work, including with older React versions.
 
-### 1. Enable view transitions on navigation
+</docs-warning>
+
+## Navigation View Transitions with React
+
+Wrap the outlet in a persistent `<ViewTransition>` boundary in a shared layout route. In Framework Mode, this can be your root route's default export; in Data and Declarative modes, use it as the component for a parent route with children:
+
+```tsx
+import { ViewTransition } from "react";
+import { Link, Outlet } from "react-router";
+
+export default function PageLayout() {
+  return (
+    <>
+      <nav>
+        <Link to="/">Home</Link>
+        <Link to="/about">About</Link>
+      </nav>
+      <ViewTransition>
+        <main>
+          <Outlet />
+        </main>
+      </ViewTransition>
+    </>
+  );
+}
+```
+
+Navigations that update the outlet cross-fade its contents. Keep the boundary mounted across navigations; you don't need to key it by location or remount the route tree. The navigation stays outside the animated region. Other updates inside the boundary can also animate when they run in a React Transition.
+
+React Router wraps router state updates in [`React.startTransition`][start-transition] by default, which lets React activate `<ViewTransition>` without additional configuration. React Transitions must remain enabled for navigation view transitions to work: do not set `useTransitions={false}` on your router.
+
+This applies to navigations from `<Link>`, `<NavLink>`, and `<Form>`, as well as programmatic navigation with `useNavigate` and `useSubmit`. No additional `startTransition` wrapper is needed.
+
+### Migrating from React Router's view transitions
+
+- Remove `viewTransition` from `<Link>`, `<NavLink>`, and `<Form>`, and remove `viewTransition: true` from navigation/submission options. React coordinates `document.startViewTransition()` itself; enabling both implementations can interrupt animations.
+- Replace `useViewTransitionState`, `isTransitioning`, and `.transitioning` styles with React's [View Transition classes][react-view-transition-classes]. Those router APIs only track the legacy transitions.
+- For shared elements such as an image moving from a list to a detail route, wrap each side in `<ViewTransition name="...">` with the same unique name. See React's [shared element example][react-shared-elements].
+- Keep React Transitions enabled. `useTransitions={false}` and synchronous updates such as `flushSync` can prevent React's animations.
+
+React's component is not a drop-in replacement for every legacy animation. In particular, React [skips view transitions for synchronous updates from `popstate`][react-router-transitions], so browser Back/Forward navigations may not animate. Browsers without View Transitions support still navigate normally.
+
+Respect reduced-motion preferences when adding animations:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation: none !important;
+  }
+}
+```
+
+## Legacy View Transitions (Deprecated)
+
+The following examples document the deprecated APIs for existing applications. These APIs are available in Framework and Data modes.
+
+### Basic View Transition
+
+#### 1. Enable view transitions on navigation
 
 The simplest way to enable view transitions is by adding the `viewTransition` prop to your `Link`, `NavLink`, or `Form` components. This automatically wraps the navigation update in `document.startViewTransition()`.
 
@@ -25,7 +84,7 @@ The simplest way to enable view transitions is by adding the `viewTransition` pr
 
 Without any additional CSS, this provides a basic cross-fade animation between pages.
 
-### 2. Enable view transitions with programmatic navigation
+#### 2. Enable view transitions with programmatic navigation
 
 When using programmatic navigation with the `useNavigate` hook, you can enable view transitions by passing the `viewTransition: true` option:
 
@@ -51,11 +110,11 @@ This provides the same cross-fade animation as using the `viewTransition` prop o
 
 For more information on using the View Transitions API, please refer to the ["Smooth transitions with the View Transition API" guide][view-transitions-guide] from the Google Chrome team.
 
-## Image Gallery Example
+### Image Gallery Example
 
 Let's build an image gallery that demonstrates how to trigger and use view transitions. We'll create a list of images that expand into a detail view with smooth animations.
 
-### 1. Create the image gallery route
+#### 1. Create the image gallery route
 
 ```tsx filename=routes/image-gallery.tsx
 import { NavLink } from "react-router";
@@ -91,7 +150,7 @@ export default function ImageGalleryRoute() {
 }
 ```
 
-### 2. Add transition styles
+#### 2. Add transition styles
 
 Define view transition names and animations for elements that should transition smoothly between routes.
 
@@ -127,7 +186,7 @@ Define view transition names and animations for elements that should transition
 }
 ```
 
-### 3. Create the image detail route
+#### 3. Create the image detail route
 
 The detail view needs to use the same view transition names to create a seamless animation.
 
@@ -151,7 +210,7 @@ export default function ImageDetailsRoute({
 }
 ```
 
-### 4. Add matching transition styles for the detail view
+#### 4. Add matching transition styles for the detail view
 
 ```css filename=app.css
 /* Match transition names from the list view */
@@ -169,11 +228,11 @@ export default function ImageDetailsRoute({
 }
 ```
 
-## Advanced Usage
+### Advanced Usage
 
 You can control view transitions more precisely using either render props or the `useViewTransitionState` hook.
 
-### 1. Using render props
+#### 1. Using render props
 
 ```tsx filename=routes/image-gallery.tsx
 <NavLink to={`/image/${idx}`} viewTransition>
@@ -201,7 +260,7 @@ You can control view transitions more precisely using either render props or the
 </NavLink>
 ```
 
-### 2. Using the `useViewTransitionState` hook
+#### 2. Using the `useViewTransitionState` hook
 
 ```tsx filename=routes/image-gallery.tsx
 function NavImage(props: { src: string; idx: number }) {
@@ -234,4 +293,9 @@ function NavImage(props: { src: string; idx: number }) {
 ```
 
 [view-transitions-api]: https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition
+[react-view-transition]: https://react.dev/reference/react/ViewTransition
+[start-transition]: https://react.dev/reference/react/startTransition
+[react-view-transition-classes]: https://react.dev/reference/react/ViewTransition#view-transition-class
+[react-shared-elements]: https://react.dev/reference/react/ViewTransition#animating-a-shared-element
+[react-router-transitions]: https://react.dev/reference/react/ViewTransition#building-view-transition-enabled-routers
 [view-transitions-guide]: https://developer.chrome.com/docs/web-platform/view-transitions

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

@@ -80,6 +80,14 @@ export default function Product({
 
 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.
 
+### Authentication and Authorization
+
+React Router runs matched route loaders in parallel and loaders can be requested independently, such as during fetcher calls or navigations that do not revalidate every matched route. Therefore it is not possible for a parent loader to "protect" child route loaders or actions via authentication checks.
+
+Unless guarded by appropriate [server middleware][auth-middleware], each protected loader and action must authenticate the request and authorize access to the data or operation before proceeding. For example, checking that a user is signed in does not establish that they have permission to access the requested project.
+
+Middleware on a protected route or a common ancestor can enforce shared checks before the protected loaders and actions run. Any permissions not enforced by that middleware must still be checked in the individual loader or action.
+
 ## Static Data Loading
 
 When pre-rendering, loaders are used to fetch data during the production build.
@@ -199,3 +207,4 @@ See also:
 [streaming]: ../../how-to/suspense
 [client-data]: ../../how-to/client-data
 [fetchers]: ../../how-to/fetchers#loading-data
+[auth-middleware]: ../../how-to/middleware#authentication

package/docs/start/framework/navigating.md

@@ -44,10 +44,6 @@ a.active {
 a.pending {
   animate: pulse 1s infinite;
 }
-
-a.transitioning {
-  /* css transition is running */
-}
 ```
 
 It also has callback props on `className`, `style`, and `children` with the states for inline styling or conditional rendering:
@@ -56,11 +52,10 @@ It also has callback props on `className`, `style`, and `children` with the stat
 // className
 <NavLink
   to="/messages"
-  className={({ isActive, isPending, isTransitioning }) =>
+  className={({ isActive, isPending }) =>
     [
       isPending ? "pending" : "",
       isActive ? "active" : "",
-      isTransitioning ? "transitioning" : "",
     ].join(" ")
   }
 >
@@ -72,11 +67,10 @@ It also has callback props on `className`, `style`, and `children` with the stat
 // style
 <NavLink
   to="/messages"
-  style={({ isActive, isPending, isTransitioning }) => {
+  style={({ isActive, isPending }) => {
     return {
       fontWeight: isActive ? "bold" : "",
       color: isPending ? "red" : "black",
-      viewTransitionName: isTransitioning ? "slide" : "",
     };
   }}
 >
@@ -87,12 +81,14 @@ It also has callback props on `className`, `style`, and `children` with the stat
 ```tsx
 // children
 <NavLink to="/tasks">
-  {({ isActive, isPending, isTransitioning }) => (
+  {({ isActive }) => (
     <span className={isActive ? "active" : ""}>Tasks</span>
   )}
 </NavLink>
 ```
 
+For animated navigations, see [View Transitions](../../how-to/view-transitions). The legacy `isTransitioning` render prop and `transitioning` class are deprecated in favor of React's `<ViewTransition>` component.
+
 ## Link
 
 Use `<Link>` when the link doesn't need active styling:

package/docs/start/framework/rendering.md

@@ -54,6 +54,43 @@ export default {
 
 Pre-rendering is a build-time operation that generates static HTML and client navigation data payloads for a list of URLs. This is useful for SEO and performance, especially for deployments without server rendering. When pre-rendering, route module loaders are used to fetch data at build time.
 
+## API-only Mode (unstable)
+
+<docs-warning>API-only Mode is experimental and may change in minor or patch releases. It is not supported in RSC Framework Mode.</docs-warning>
+
+Set `ssr: "unstable_api-only"` to keep a runtime server for loaders, actions, and route discovery while disabling production server-side document rendering:
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: "unstable_api-only",
+} satisfies Config;
+```
+
+Without prerendering, the build generates a root-only `index.html` shell using the root `HydrateFallback`, like [SPA Mode](../../how-to/spa). The browser fetches server loader data as it initializes the page. Routes can use server `loader` and `action` exports without requiring `clientLoader` or `clientAction` wrappers. Lazy route discovery remains enabled by default.
+
+You can also [combine API-only Mode with prerendering](../../how-to/pre-rendering#pre-rendering-with-api-only-mode-unstable) to serve complete HTML for selected paths and a SPA fallback for other paths.
+
+Deploy both `build/client` and the runtime server build. Serve assets, prerendered documents, and the SPA fallback from the client build; send `.data` and route discovery requests (`/__manifest` by default) to the React Router request handler. The production API-only handler returns `404` for document requests. `react-router-serve` handles this routing automatically.
+
+### Using a separate API origin
+
+By default, data and route discovery requests use the same origin as the client application. Set `unstable_apiServerOrigin` to use a separate API server:
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: "unstable_api-only",
+  unstable_apiServerOrigin: "https://api.example.com",
+} satisfies Config;
+```
+
+This option applies to loader, action, and route discovery requests only in API-only Mode. Use an origin without a path, query, or hash. Configure CORS on the API server and allow the client origin via [`allowedActionOrigins`](../../api/framework-conventions/react-router.config.ts#allowedactionorigins) for cross-origin action submissions. Requests use the browser's default `same-origin` credential policy; this option does not enable sending cookies to a different origin.
+
+To customize JavaScript-issued requests with authentication headers or cross-origin credentials, see [Custom Fetch](../../how-to/custom-fetch). Native data prefetches bypass custom fetch.
+
 ---
 
 Next: [Data Loading](./data-loading)

package/docs/upgrading/future.md

@@ -17,9 +17,6 @@ We highly recommend you make a commit after each step and ship it instead of doi
 
 [MODES: framework, data, declarative]
 
-<br/>
-<br/>
-
 React Router v9 will require the following minimum versions (as of now). You can prepare for the upgrade by updating them while still on v8:
 
 - `node@24+`
@@ -50,9 +47,6 @@ We document some [unstable] flags here as a reference for folks contributing to
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 **Background**
 
 Now that the Web Streams API is [stable](https://nodejs.org/docs/latest-v22.x/api/webstreams.html) in Node 22+, it's viable for React Router to use React's [`renderToReadableStream`](https://react.dev/reference/react-dom/server/renderToReadableStream) in the server entry.
@@ -83,9 +77,6 @@ No code changes are required. If your app has a custom `entry.server.tsx`, this
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 **Background**
 
 This flag lets React Router provide Vite's dependency optimizer with the client entry file and route module files. This can improve dependency optimization in development, but the behavior is still experimental.
@@ -110,9 +101,6 @@ No code changes are required. If you run into dependency optimization issues aft
 
 [MODES: data]
 
-<br/>
-<br/>
-
 **Background**
 
 This flag opts Data Routers into a new (and vastly more efficient) route matcher

package/docs/upgrading/v7.md

@@ -13,9 +13,6 @@ We highly recommend you make a commit after each step and ship it instead of doi
 
 [MODES: framework, data, declarative]
 
-<br/>
-<br/>
-
 React Router v8 requires the following minimum versions. Update them before updating React Router to v8:
 
 - `node@22.22+`
@@ -42,9 +39,6 @@ npm install react-router@7 @react-router/{dev,node,etc.}@7
 
 [MODES: framework, data]
 
-<br/>
-<br/>
-
 **Background**
 
 Middleware allows you to run code before and after the [`Response`][Response] generation for the matched path. This enables common patterns like authentication, logging, error handling, and data preprocessing in a reusable way. Please see the [docs](../how-to/middleware) for more information.
@@ -86,9 +80,6 @@ If you're using the `context` parameter in `loader` and `action` functions, you
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 **Background**
 
 This feature enables splitting client-side route exports (`clientLoader`, `clientAction`, `clientMiddleware`, `HydrateFallback`) into separate chunks that can be loaded independently from the route component. This allows these exports to be fetched and executed while the component code is still downloading, improving performance for client-side data loading.
@@ -115,9 +106,6 @@ No code changes are required. This is an optimization feature that works automat
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 **Background**
 
 This enables support for the experimental Vite Environment API, which provides a more flexible and powerful way to configure Vite environments. This is only available when using Vite 6+.
@@ -173,9 +161,6 @@ See the [`node-custom-server` template][node-custom-server-template] for a compl
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 **Background**
 
 By default, React Router normalizes the `request.url` passed to your `loader`, `action`, and `middleware` functions by removing React Router's internal implementation details. Specifically, it removes `.data` suffixes and internal search parameters like `?index` and `?_routes`.
@@ -185,7 +170,7 @@ This flag eliminates that normalization and passes the raw HTTP `request` instan
 - Reduces server-side overhead by eliminating multiple `new Request()` calls on the critical path
 - Allows you to distinguish document from data requests in your handlers based on the presence of a `.data` suffix (useful for [observability] purposes)
 
-If you were previously relying on the normalization of `request.url`, you can switch to use the new sibling `url` parameter which contains a `URL` instance representing the normalized location.
+If you were previously relying on the normalization of `request.url`, you can switch to use the new sibling `url` parameter which contains a `URL` instance with React Router's internal implementation details removed.
 
 👉 **Enable the Flag**
 
@@ -215,8 +200,8 @@ export async function loader({
   }
 }
 
-// ✅ After: use `url` for normalized routing logic and `request.url`
-// for raw routing logic
+// ✅ After: use `url` with React Router's internal details removed
+// and `request.url` for the original request URL
 export async function loader({
   request,
   url,
@@ -236,9 +221,6 @@ export async function loader({
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 **Background**
 
 React Router serves Framework mode data requests from `.data` URLs. Previously, data requests for routes with and without trailing slashes could map to the same `.data` URL because trailing slashes were not considered during URL generation. This flag preserves trailing slash semantics for data request URLs to avoid ambiguity when your app distinguishes between trailing-slash and non-trailing-slash URLs.
@@ -293,9 +275,6 @@ The changes in this section are not controlled by future flags, but you can upda
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 **Background**
 
 React Router v8 removed deprecated `data` fields in favor of `loaderData` in a few places:
@@ -352,9 +331,6 @@ export default function Component({ matches, loaderData }: ComponentProps) {
 
 [MODES: framework, data, declarative]
 
-<br/>
-<br/>
-
 **Background**
 
 React Router v8 removes the `react-router-dom` re-export package. In v8, you should import DOM-specific APIs from `react-router/dom` and everything else from `react-router`.
@@ -385,9 +361,6 @@ For DOM-specific APIs, import from `react-router/dom`:
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 **Background**
 
 React Router v8 removes the React Router Cloudflare dev proxy. Cloudflare projects should use [`@cloudflare/vite-plugin`][cloudflare-vite-plugin] instead.
@@ -415,9 +388,6 @@ export default defineConfig({
 
 [MODES: framework]
 
-<br/>
-<br/>
-
 **Background**
 
 In v7, the `@react-router/architect` adapter uses `X-Forwarded-Host` when creating the `request`, falling back to the `Host` header. In React Router v8, the adapter uses `event.requestContext.domainName` by default, falling back to the `Host` header.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-router",
   "type": "module",
-  "version": "8.4.0",
+  "version": "8.5.1",
   "description": "Declarative routing for React",
   "keywords": [
     "react",
@@ -104,10 +104,18 @@
     "wireit": "0.14.12"
   },
   "peerDependencies": {
+    "@types/react": ">=19.2.0",
+    "@types/react-dom": ">=19.2.0",
     "react": ">=19.2.7",
     "react-dom": ">=19.2.7"
   },
   "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "@types/react-dom": {
+      "optional": true
+    },
     "react-dom": {
       "optional": true
     }