Update middleware docs

brophdawg11 · brophdawg11 · commit 88beda8df690 · 2025-07-28T17:01:18.000-04:00
diff --git a/docs/how-to/middleware.md b/docs/how-to/middleware.md
@@ -7,17 +7,17 @@ unstable: true
 
 <docs-warning>The middleware feature is currently experimental and subject to breaking changes. Use the `future.unstable_middleware` flag to enable it.</docs-warning>
 
-Middleware allows you to run code before and after your route handlers (loaders, actions, and components) execute. This enables common patterns like authentication, logging, error handling, and data preprocessing in a reusable way.
+Middleware allows you to run code before and after the `Response` generation for the matched path. This enables common patterns like authentication, logging, error handling, and data preprocessing in a reusable way.
 
-Middleware runs in a nested chain, executing from parent routes to child routes on the way "down" to your route handlers, then from child routes back to parent routes on the way "up" after your handlers complete.
+Middleware runs in a nested chain, executing from parent routes to child routes on the way "down" to your route handlers, then from child routes back to parent routes on the way "up" after a `Response` is generated.
 
 For example, on a `GET /parent/child` request, the middleware would run in the following order:
 
 ```text
 - Root middleware start
   - Parent middleware start
     - Child middleware start
-      - Run loaders
+      - Run loaders, generate HTML Response
     - Child middleware end
   - Parent middleware end
 - Root middleware end
@@ -39,11 +39,12 @@ export default {
 } satisfies Config;
 ```
 
-<docs-warning>By enabling the middleware feature, you change the type of the `context` parameter to your loaders and actions. Please pay attention to the section on [getLoadContext](#custom-server-with-getloadcontext) below if you are actively using `context` today.</docs-warning>
+<docs-warning>By enabling the middleware feature, you change the type of the `context` parameter to your loaders and actions. Please pay attention to the section on [getLoadContext](#changes-to-getloadcontextapploadcontext) below if you are actively using `context` today.</docs-warning>
 
 ### 2. Create a context
 
-Create type-safe context objects using `unstable_createContext`:
+Middleware uses a `context` provider instance to provide data down the middleware chain.
+You can create type-safe context objects using `unstable_createContext`:
 
 ```ts filename=app/context.ts
 import { unstable_createContext } from "react-router";
@@ -104,6 +105,22 @@ export default function Dashboard({
 }
 ```
 
+#### 4. Update your `getLoadContext` function (if applicable)
+
+If you're using a custom server and a `getLoadContext` function, you will need to update your implementation to return a Map of contexts and values, instead of a JavaScript object:
+
+```diff
++import { unstable_createContext } from "react-router";
+import { createDb } from "./db";
++
++const dbContext = unstable_createContext<Database>();
+
+function getLoadContext(req, res) {
+-  return { db: createDb() };
++  const map = new Map([[dbContext, createDb()]]);
+}
+```
+
 ## Core Concepts
 
 ### Server vs Client Middleware
@@ -117,9 +134,29 @@ export default function Dashboard({
 
 - Client-side navigations and fetcher calls
 
+### Context API
+
+The new context system provides type safety and prevents naming conflicts:
+
+```ts
+// ✅ Type-safe
+import { unstable_createContext } from "react-router";
+const userContext = unstable_createContext<User>();
+
+// Later in middleware/loaders
+context.set(userContext, user); // Must be User type
+const user = context.get(userContext); // Returns User type
+
+// ❌ Old way (no type safety)
+// context.user = user; // Could be anything
+```
+
 ### The `next` Function
 
-The `next` function runs the next middleware in the chain, or the route handlers if it's the leaf route middleware:
+The `next` function logic depends on which route middleware it's being called from:
+
+- When called from a non-leaf middleware, it runs the next middleware in the chain
+- When called from the leaf middleware, it executes any route handlers and generates the resulting `Response` for the request
 
 ```ts
 const middleware = async ({ context }, next) => {
@@ -152,21 +189,87 @@ const authMiddleware = async ({ request, context }) => {
 };
 ```
 
-### Context API
+### `next()` and Error Handling
 
-The new context system provides type safety and prevents naming conflicts:
+`next()` is not designed to throw errors under normal conditions, so you generally shouldn't find yourself wrapping `next` in a `try`/`catch`. The responsibility of the `next()` function is to return a `Response` for the current `Request`, so as long as that can be completed, `next()` will return the Response and won't `throw`. Even if a `loader` throws an error, or a component fails to render, React Router already handles those by rendering the nearest `ErrorBoundary`, so a Response is still generated without issue.
+
+This behavior is important to allow middleware patterns such as automatically setting required headers on outgoing responses (i.e., committing a session) from a root middleware. If any error caused that to throw, we'd miss the execution of ancestor middleware son thew way out and those required headers wouldn't be set.
+
+The only cases in which `next()` _should_ throw are if we fail to generate a Response. There's a few ways in which this could happen:
+
+- A middleware can short circuit the rest of the request and throw a `Response` (usually a `redirect`)
+- If the logic directly inside of a middleware function throws, that will cause the ancestor `next()` function to throw
+
+## Changes to `getLoadContext`/`AppLoadContext`
+
+<docs-info>This only applies if you are using a custom server and a custom `getLoadContext` function</docs-info>
+
+Middleware introduces a breaking change to the `context` parameter generated by `getLoadContext` and passed to your loaders and actions. The current approach of a module-augmented `AppLoadContext` isn't really type-safe and instead just sort of tells TypeScript to "trust me".
+
+Middleware needs an equivalent `context` on the client for `clientMiddleware`, but we didn't want to duplicate this pattern from the server that we already weren't thrilled with, so we decided to introduce a new API where we could tackle type-safety.
+
+When opting into middleware, the `context` parameter changes to an instance of `RouterContextProvider`:
 
 ```ts
-// ✅ Type-safe
+let dbContext = unstable_createContext<Database>();
+let context = new unstable_RouterContextProvider();
+context.set(dbContext, getDb());
+//                     ^ type-safe
+let db = context.get(dbContext);
+//  ^ Database
+```
+
+If you're using a custom server and a `getLoadContext` function, you will need to update your implementation to return a `Map` of contexts and values, instead of a JavaScript object:
+
+```diff
++import { unstable_createContext } from "react-router";
+import { createDb } from "./db";
++
++const dbContext = unstable_createContext<Database>();
+
+function getLoadContext(req, res) {
+-  return { db: createDb() };
++  const map = new Map([[dbContext, createDb()]]);
+}
+```
+
+### Migration from `AppLoadContext`
+
+If you're currently using `AppLoadContext`, you can migrate most easily by creating a context for your existing object:
+
+```ts filename=app/context.ts
 import { unstable_createContext } from "react-router";
-const userContext = unstable_createContext<User>();
 
-// Later in middleware/loaders
-context.set(userContext, user); // Must be User type
-const user = context.get(userContext); // Returns User type
+declare module "@react-router/server-runtime" {
+  interface AppLoadContext {
+    db: Database;
+    user: User;
+  }
+}
 
-// ❌ Old way (no type safety)
-// context.user = user; // Could be anything
+const myLoadContext =
+  unstable_createContext<AppLoadContext>();
+```
+
+Update your `getLoadContext` function to return a Map with the context initial value:
+
+```diff filename=server.ts
+function getLoadContext() {
+  const loadContext = {...};
+-  return loadContext;
++  return new Map([
++    [myLoadContext, loadContext]]
++  );
+}
+```
+
+Update your loaders/actions to read from the new context instance:
+
+```diff filename=app/routes/example.tsx
+export function loader({ context }: Route.LoaderArgs) {
+-  const { db, user } = context;
++  const { db, user } = context.get(myLoadContext);
+}
 ```
 
 ## Common Patterns
@@ -233,25 +336,6 @@ export const loggingMiddleware = async (
 };
 ```
 
-### Error Handling
-
-```tsx filename=app/middleware/error-handling.ts
-export const errorMiddleware = async (
-  { context },
-  next,
-) => {
-  try {
-    return await next();
-  } catch (error) {
-    // Log error
-    console.error("Route error:", error);
-
-    // Re-throw to let React Router handle it
-    throw error;
-  }
-};
-```
-
 ### 404 to CMS Redirect
 
 ```tsx filename=app/middleware/cms-fallback.ts
@@ -293,37 +377,6 @@ export const headersMiddleware = async (
 };
 ```
 
-## Client-Side Middleware
-
-Client middleware works similarly but doesn't return responses:
-
-```tsx filename=app/routes/dashboard.tsx
-import { userContext } from "~/context";
-
-export const unstable_clientMiddleware = [
-  ({ context }) => {
-    // Set up client-side user data
-    const user = getLocalUser();
-    context.set(userContext, user);
-  },
-
-  async ({ context }, next) => {
-    console.log("Starting client navigation");
-    await next();
-    console.log("Client navigation complete");
-  },
-];
-
-export async function clientLoader({
-  context,
-}: Route.ClientLoaderArgs) {
-  const user = context.get(userContext);
-  return { user };
-}
-```
-
-## Advanced Usage
-
 ### Conditional Middleware
 
 ```tsx
@@ -371,58 +424,31 @@ export async function loader({
 }
 ```
 
-### Custom Server with getLoadContext
-
-If you're using a custom server, update your `getLoadContext` function:
-
-```ts filename=app/entry.server.tsx
-import { unstable_createContext } from "react-router";
-import type { unstable_InitialContext } from "react-router";
-
-const dbContext = unstable_createContext<Database>();
-
-function getLoadContext(req, res): unstable_InitialContext {
-  const map = new Map();
-  map.set(dbContext, database);
-  return map;
-}
-```
-
-### Migration from AppLoadContext
-
-If you're currently using `AppLoadContext`, you can migrate most easily by creating a context for your existing object:
-
-```ts filename=app/context.ts
-import { unstable_createContext } from "react-router";
-
-declare module "@react-router/server-runtime" {
-  interface AppLoadContext {
-    db: Database;
-    user: User;
-  }
-}
+## Client-Side Middleware
 
-const myLoadContext =
-  unstable_createContext<AppLoadContext>();
-```
+Client middleware works similar to server-side middleware but doesn't return responses because it's not running ion response to an HTTP `Request`:
 
-Update your `getLoadContext` function to return a Map with the context initial value:
+```tsx filename=app/routes/dashboard.tsx
+import { userContext } from "~/context";
 
-```diff filename=app/entry.server.tsx
-function getLoadContext() {
-  const loadContext = {...};
--  return loadContext;
-+  return new Map([
-+    [myLoadContext, appLoadContextInstance]]
-+  );
-}
-```
+export const unstable_clientMiddleware = [
+  ({ context }) => {
+    // Set up client-side user data
+    const user = getLocalUser();
+    context.set(userContext, user);
+  },
 
-Update your loaders/actions to read from the new context instance:
+  async ({ context }, next) => {
+    console.log("Starting client navigation");
+    await next(); // 👈 No return value
+    console.log("Client navigation complete");
+  },
+];
 
-```diff filename=app/routes/example.tsx
-export function loader({ context }: Route.LoaderArgs) {
--  const { db, user } = context;
-+  const { db, user } = context.get(myLoadContext);
+export async function clientLoader({
+  context,
+}: Route.ClientLoaderArgs) {
+  const user = context.get(userContext);
+  return { user };
 }
 ```
