Merge branch 'main' into release-next

brophdawg11 · brophdawg11 · commit 6cce04faab77 · 2025-08-14T10:51:41.000-04:00
diff --git a/.github/workflows/close-feature-pr.yml b/.github/workflows/close-feature-pr.yml
@@ -17,7 +17,7 @@ jobs:
       pull-requests: write
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: 🚪 Close PR
         env:
diff --git a/.github/workflows/close-no-repro-issue.yml b/.github/workflows/close-no-repro-issue.yml
@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: 🚪 Close issue
         env:
diff --git a/.github/workflows/close-no-repro-issues.yml b/.github/workflows/close-no-repro-issues.yml
@@ -25,7 +25,7 @@ jobs:
       GH_TOKEN: ${{ github.token }}
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: 📦 Setup pnpm
         uses: pnpm/action-setup@v4.1.0
diff --git a/.github/workflows/deduplicate-lock-file.yml b/.github/workflows/deduplicate-lock-file.yml
@@ -18,7 +18,7 @@ jobs:
 
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           token: ${{ secrets.FORMAT_PAT }}
 
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -26,7 +26,7 @@ jobs:
 
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           token: ${{ secrets.FORMAT_PAT }}
           ref: ${{ github.event.inputs.branch }}
diff --git a/.github/workflows/format.yml b/.github/workflows/format.yml
@@ -17,7 +17,7 @@ jobs:
 
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           token: ${{ secrets.FORMAT_PAT }}
 
diff --git a/.github/workflows/release-comments.yml b/.github/workflows/release-comments.yml
@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
diff --git a/.github/workflows/release-experimental.yml b/.github/workflows/release-experimental.yml
@@ -18,7 +18,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: ${{ github.event.inputs.branch }}
           # checkout using a custom token so that we can push later on
diff --git a/.github/workflows/release-nightly.yml b/.github/workflows/release-nightly.yml
@@ -29,7 +29,7 @@ jobs:
       NEXT_VERSION: ${{ steps.version.outputs.NEXT_VERSION }}
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: dev
           # checkout using a custom token so that we can push later on
diff --git a/.github/workflows/release-stage-2-alpha.yml b/.github/workflows/release-stage-2-alpha.yml
@@ -22,7 +22,7 @@ jobs:
           echo "SHA: ${{ github.event.pull_request.head.sha }}"
 
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: ${{ github.event.pull_request.head.sha }}
 
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -27,7 +27,7 @@ jobs:
       pull-requests: write # enable opening a PR for the release
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
@@ -78,7 +78,7 @@ jobs:
       package_version: ${{ steps.find_package_version.outputs.package_version }}
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: 📦 Setup pnpm
         uses: pnpm/action-setup@v4
diff --git a/.github/workflows/shared-build.yml b/.github/workflows/shared-build.yml
@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: 📦 Setup pnpm
         uses: pnpm/action-setup@v4
diff --git a/.github/workflows/shared-integration.yml b/.github/workflows/shared-integration.yml
@@ -38,7 +38,7 @@ jobs:
     runs-on: ${{ inputs.os }}
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: 📦 Setup pnpm
         uses: pnpm/action-setup@v4
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -33,7 +33,7 @@ jobs:
 
     steps:
       - name: ⬇️ Checkout repo
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: 📦 Setup pnpm
         uses: pnpm/action-setup@v4
diff --git a/contributors.yml b/contributors.yml
@@ -72,6 +72,7 @@
 - chasinhues
 - chensokheng
 - chr33s
+- chrille0313
 - chrisngobanh
 - christopherchudzicki
 - ChristophP
diff --git a/docs/api/hooks/useNavigate.md b/docs/api/hooks/useNavigate.md
@@ -135,3 +135,41 @@ For example, if you have a tab interface connected to search params in the
 middle of a page, and you don't want it to scroll to the top when a tab is
 clicked.
 
+### Return Type Augmentation
+
+Internally, `useNavigate` uses a separate implementation when you are in
+Declarative mode versus Data/Framework mode - the primary difference being
+that the latter is able to return a stable reference that does not change
+identity across navigations. The implementation in Data/Framework mode also
+returns a [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
+that resolves when the navigation is completed. This means the return type of
+`useNavigate` is `void | Promise<void>`. This is accurate, but can lead to
+some red squigglies based on the union in the return value:
+
+- If you're using `typescript-eslint`, you may see errors from
+  [`@typescript-eslint/no-floating-promises`](https://typescript-eslint.io/rules/no-floating-promises)
+- In Framework/Data mode, `React.use(navigate())` will show a false-positive
+  `Argument of type 'void | Promise<void>' is not assignable to parameter of
+  type 'Usable<void>'` error
+
+The easiest way to work around these issues is to augment the type based on the
+router you're using:
+
+```ts
+// If using <BrowserRouter>
+declare module "react-router" {
+  interface NavigateFunction {
+    (to: To, options?: NavigateOptions): void;
+    (delta: number): void;
+  }
+}
+
+// If using <RouterProvider> or Framework mode
+declare module "react-router" {
+  interface NavigateFunction {
+    (to: To, options?: NavigateOptions): Promise<void>;
+    (delta: number): Promise<void>;
+  }
+}
+```
+
diff --git a/docs/api/other-api/adapter.md b/docs/api/other-api/adapter.md
@@ -0,0 +1,170 @@
+---
+title: "@react-router/{adapter}"
+---
+
+# Server Adapters
+
+## Official Adapters
+
+Idiomatic React Router apps can generally be deployed anywhere because React Router adapts the server's request/response to the [Web Fetch API][web-fetch-api]. It does this through adapters. We maintain a few adapters:
+
+- `@react-router/architect`
+- `@react-router/cloudflare`
+- `@react-router/express`
+
+These adapters are imported into your server's entry and are not used inside your React Router app itself.
+
+If you initialized your app with `npx create-react-router@latest` with something other than the built-in [React Router App Server][rr-serve] (`@react-router/serve`), you will note a `server/index.js` file that imports and uses one of these adapters.
+
+<docs-info>If you're using the built-in React Router App Server, you don't interact with this API</docs-info>
+
+Each adapter has the same API. In the future, we may have helpers specific to the platform you're deploying to.
+
+## `@react-router/express`
+
+[Reference Documentation ↗](https://api.reactrouter.com/v7/modules/_react_router_express.html)
+
+Here's an example with [Express][express]:
+
+```ts lines=[1-3,11-22]
+const {
+  createRequestHandler,
+} = require("@react-router/express");
+const express = require("express");
+
+const app = express();
+
+// needs to handle all verbs (GET, POST, etc.)
+app.all(
+  "*",
+  createRequestHandler({
+    // `react-router build` and `react-router dev` output files to a build directory,
+    // you need to pass that build to the request handler
+    build: require("./build"),
+
+    // Return anything you want here to be available as `context` in your
+    // loaders and actions. This is where you can bridge the gap between your
+    // server and React Router
+    getLoadContext(req, res) {
+      return {};
+    },
+  }),
+);
+```
+
+### Migrating from the React Router App Server
+
+If you started an app with the [React Router App Server][rr-serve] but find that you want to take control over the Express server and customize it, it should be fairly straightforward to migrate way from `@react-router/serve`.
+
+You can refer to the [Express template][express-template] as a reference, but here are the main changes you will need to make:
+
+**1. Update deps**
+
+```shellscript nonumber
+npm uninstall @react-router/serve
+npm install @react-router/express compression express morgan cross-env
+npm install --save-dev @types/express @types/express-serve-static-core @types/morgan
+```
+
+**2. Add a server**
+
+Create your React Router Express server in `server/app.ts`:
+
+```ts filename=server/app.ts
+import "react-router";
+import { createRequestHandler } from "@react-router/express";
+import express from "express";
+
+export const app = express();
+
+app.use(
+  createRequestHandler({
+    build: () =>
+      import("virtual:react-router/server-build"),
+  }),
+);
+```
+
+Copy the [`server.js`][express-template-server-js] into your app. This is the boilerplate setup we recommend to allow the same server code to run both the development and production builds of your app. Two separate files are used here so that the main Express server code can be written in TypeScript (`server/app.ts`) and compiled into your server build by React Router, and then executed via `node server.js`.
+
+**3. Update `vite.config.ts` to compile the server**
+
+```tsx filename=vite.config.ts lines=[6-10]
+import { reactRouter } from "@react-router/dev/vite";
+import { defineConfig } from "vite";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+export default defineConfig(({ isSsrBuild }) => ({
+  build: {
+    rollupOptions: isSsrBuild
+      ? { input: "./server/app.ts" }
+      : undefined,
+  },
+  plugins: [reactRouter(), tsconfigPaths()],
+}));
+```
+
+**4. Update `package.json` scripts**
+
+Update the `dev` and `start` scripts to use your new Express server:
+
+```json filename=package.json
+{
+  // ...
+  "scripts": {
+    "dev": "cross-env NODE_ENV=development node server.js",
+    "start": "node server.js"
+    // ...
+  }
+  // ...
+}
+```
+
+## `@react-router/cloudflare`
+
+[Reference Documentation ↗](https://api.reactrouter.com/v7/modules/_react_router_cloudflare.html)
+
+Here's an example with Cloudflare:
+
+```ts
+import { createRequestHandler } from "react-router";
+
+declare module "react-router" {
+  export interface AppLoadContext {
+    cloudflare: {
+      env: Env;
+      ctx: ExecutionContext;
+    };
+  }
+}
+
+const requestHandler = createRequestHandler(
+  () => import("virtual:react-router/server-build"),
+  import.meta.env.MODE,
+);
+
+export default {
+  async fetch(request, env, ctx) {
+    return requestHandler(request, {
+      cloudflare: { env, ctx },
+    });
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+## `@react-router/node`
+
+While not a direct "adapter" like the above, this package contains utilities for working with Node-based adapters.
+
+[Reference Documentation ↗](https://api.reactrouter.com/v7/modules/_react_router_node.html)
+
+### Node Version Support
+
+React Router officially supports **Active** and **Maintenance** [Node LTS versions][node-releases] at any given point in time. Dropped support for End of Life Node versions is done in a React Router Minor release.
+
+[express]: https://expressjs.com
+[node-releases]: https://nodejs.org/en/about/previous-releases
+[web-fetch-api]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+[rr-serve]: ./serve
+[express-template]: https://github.com/remix-run/react-router-templates/tree/main/node-custom-server
+[express-template-server-js]: https://github.com/remix-run/react-router-templates/blob/main/node-custom-server/server.js
diff --git a/docs/api/other-api/dev.md b/docs/api/other-api/dev.md
diff --git a/docs/api/other-api/index.md b/docs/api/other-api/index.md
diff --git a/docs/api/other-api/serve.md b/docs/api/other-api/serve.md
diff --git a/docs/api/utils/index.md b/docs/api/utils/index.md
diff --git a/docs/how-to/middleware.md b/docs/how-to/middleware.md
diff --git a/docs/start/data/installation.md b/docs/start/data/installation.md
diff --git a/packages/react-router/lib/hooks.tsx b/packages/react-router/lib/hooks.tsx
