Update middleware getLoadContext approach (#14097)

Author: brophdawg11

.changeset/plenty-cycles-whisper.md

@@ -0,0 +1,5 @@
+---
+"react-router": patch
+---
+
+- [UNSTABLE] When middleware is enabled, make the `context` parameter read-only (via `Readonly<unstable_RouterContextProvider>`) so that TypeScript will not allow you to write arbitrary fields to it in loaders, actions, or middleware.

.changeset/shiny-ghosts-happen.md

@@ -0,0 +1,12 @@
+---
+"@react-router/cloudflare": patch
+"@react-router/architect": patch
+"@react-router/express": patch
+"@react-router/node": patch
+"react-router": patch
+---
+
+[UNSTABLE] Change `getLoadContext` signature (`type GetLoadContextFunction`) when `future.unstable_middleware` is enabled so that it returns an `unstable_RouterContextProvider` instance instead of a `Map` used to contruct the instance internally
+
+- This also removes the `type unstable_InitialContext` export
+- ⚠️ This is a breaking change if you have adopted middleware and are using a custom server with a `getLoadContext` function

.changeset/tiny-turtles-compete.md

@@ -0,0 +1,7 @@
+---
+"react-router": patch
+---
+
+[UNSTABLE] Change the `unstable_getContext` signature on `RouterProvider`/`HydratedRouter`/`unstable_RSCHydratedRouter` so that it returns an `unstable_RouterContextProvider` instance instead of a `Map` used to contruct the instance internally
+
+- ⚠️ This is a breaking change if you have adopted the `unstable_getContext` prop

docs/how-to/middleware.md

@@ -107,17 +107,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:
+If you're using a custom server and a `getLoadContext` function, you will need to update your implementation to return an instance of `unstable_RouterContextProvider`, instead of a JavaScript object:
 
 ```diff
-+import { unstable_createContext } from "react-router";
++import {
++  unstable_createContext,
++  unstable_RouterContextProvider,
++} 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()]]);
++  return new unstable_RouterContextProvider(
++    new Map([[dbContext, createDb()]])
++  );
 }
 ```
 
@@ -224,58 +229,52 @@ 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:
+If you're using a custom server and a `getLoadContext` function, you will need to update your implementation to return an instance of `unstable_RouterContextProvider`, instead of a plain JavaScript object:
 
 ```diff
-+import { unstable_createContext } from "react-router";
++import {
++  unstable_createContext,
++  unstable_RouterContextProvider,
++} 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()]]);
++  return new unstable_RouterContextProvider(
++    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:
+If you're currently using `AppLoadContext`, you can migrate incrementally by using your existing module augmentation to augment `unstable_RouterContextProvider` instead of `AppLoadContext`. Then, update your `getLoadContext` function to return an instance of `unstable_RouterContextProvider`:
 
-```ts filename=app/context.ts
-import { unstable_createContext } from "react-router";
-
-declare module "@react-router/server-runtime" {
-  interface AppLoadContext {
+```diff
+declare module "react-router" {
+-  interface AppLoadContext {
++  interface unstable_RouterContextProvider {
     db: Database;
     user: User;
   }
 }
 
-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]]
-+  );
++  let context = new unstable_RouterContextProvider();
++  Object.assign(context, loadContext);
++  return context;
 }
 ```
 
-Update your loaders/actions to read from the new context instance:
+This allows you to leave your loaders/actions untouched during initial adoption of middleware, since they can still read values directly (i.e., `context.db`).
 
-```diff filename=app/routes/example.tsx
-export function loader({ context }: Route.LoaderArgs) {
--  const { db, user } = context;
-+  const { db, user } = context.get(myLoadContext);
-}
-```
+<docs-warning>This approach is only intended to be used as a migration strategy when adopting middleware in React Router v7, allowing you to incrementally migrate to `context.set`/`context.get`. It is not safe to assume this approach will work in the next major version of React Router.</docs-warning>
+
+<docs-warning>The `unstable_RouterContextProvider` class is also used for the client-side `context` parameter via `<HydratedRouter unstable_getContext>` and `<RouterProvider unstable_getContext>`. Since `AppLoadContext` is primarily intended as a hand-off from your HTTP server into the React Router handlers, you need to be aware that these augmented fields will not be available in `clientMiddleware`, `clientLoader`, or `clientAction` functions even thought TypeScript will tell you they are (unless, of course, you provide the fields via `unstable_getContext` on the client).</docs-warning>
 
 ## Common Patterns
 

integration/browser-entry-test.ts

@@ -87,29 +87,33 @@ test("allows users to pass a client side context to HydratedRouter", async ({
   let fixture = await createFixture({
     files: {
       "app/entry.client.tsx": js`
-        import { unstable_createContext } from "react-router";
+        import { unstable_createContext, unstable_RouterContextProvider } from "react-router";
         import { HydratedRouter } from "react-router/dom";
         import { startTransition, StrictMode } from "react";
         import { hydrateRoot } from "react-dom/client";
 
-        export const initialContext = new unstable_createContext('empty');
+        export const myContext = new unstable_createContext('foo');
 
         startTransition(() => {
           hydrateRoot(
             document,
             <StrictMode>
-              <HydratedRouter unstable_getContext={() => {
-                return new Map([[initialContext, 'bar']]);
-               }} />
+              <HydratedRouter
+                unstable_getContext={() => {
+                  return new unstable_RouterContextProvider([
+                    [myContext, 'bar']
+                  ]);
+                }}
+              />
             </StrictMode>
           );
         });
       `,
       "app/routes/_index.tsx": js`
-        import { initialContext } from "../entry.client";
+        import { myContext } from "../entry.client";
 
         export function clientLoader({ context }) {
-          return context.get(initialContext);
+          return context.get(myContext);
         }
         export default function Index({ loaderData }) {
           return <h1>Hello, {loaderData}</h1>

packages/react-router-architect/server.ts

@@ -2,7 +2,7 @@ import type {
   AppLoadContext,
   UNSAFE_MiddlewareEnabled as MiddlewareEnabled,
   ServerBuild,
-  unstable_InitialContext,
+  unstable_RouterContextProvider,
 } from "react-router";
 import { createRequestHandler as createReactRouterRequestHandler } from "react-router";
 import { readableStreamToString } from "@react-router/node";
@@ -27,7 +27,7 @@ type MaybePromise<T> = T | Promise<T>;
 export type GetLoadContextFunction = (
   event: APIGatewayProxyEventV2,
 ) => MiddlewareEnabled extends true
-  ? MaybePromise<unstable_InitialContext>
+  ? MaybePromise<unstable_RouterContextProvider>
   : MaybePromise<AppLoadContext>;
 
 export type RequestHandler = APIGatewayProxyHandlerV2;

packages/react-router-cloudflare/worker.ts

@@ -2,7 +2,7 @@ import type {
   AppLoadContext,
   UNSAFE_MiddlewareEnabled as MiddlewareEnabled,
   ServerBuild,
-  unstable_InitialContext,
+  unstable_RouterContextProvider,
 } from "react-router";
 import { createRequestHandler as createReactRouterRequestHandler } from "react-router";
 import { type CacheStorage } from "@cloudflare/workers-types";
@@ -37,7 +37,7 @@ export type GetLoadContextFunction<
     };
   };
 }) => MiddlewareEnabled extends true
-  ? MaybePromise<unstable_InitialContext>
+  ? MaybePromise<unstable_RouterContextProvider>
   : MaybePromise<AppLoadContext>;
 
 export type RequestHandler<Env = any> = PagesFunction<Env>;

packages/react-router-dev/vite/cloudflare-dev-proxy.ts

@@ -3,13 +3,13 @@ import {
   type AppLoadContext,
   type ServerBuild,
   type UNSAFE_MiddlewareEnabled,
-  type unstable_InitialContext,
+  type unstable_RouterContextProvider,
 } from "react-router";
 import { type Plugin } from "vite";
 import { type GetPlatformProxyOptions, type PlatformProxy } from "wrangler";
 
 import { fromNodeRequest, toNodeRequest } from "./node-adapter";
-import { preloadVite, getVite } from "./vite";
+import { preloadVite } from "./vite";
 import { type ResolvedReactRouterConfig, loadConfig } from "../config/config";
 
 let serverBuildId = "virtual:react-router/server-build";
@@ -26,7 +26,7 @@ type GetLoadContext<Env, Cf extends CfProperties> = (args: {
   request: Request;
   context: LoadContext<Env, Cf>;
 }) => UNSAFE_MiddlewareEnabled extends true
-  ? MaybePromise<unstable_InitialContext>
+  ? MaybePromise<unstable_RouterContextProvider>
   : MaybePromise<AppLoadContext>;
 
 function importWrangler() {

packages/react-router-dev/vite/plugin.ts

@@ -25,7 +25,7 @@ import type {
   ServerBuild,
   DataRouteObject,
   UNSAFE_MiddlewareEnabled as MiddlewareEnabled,
-  unstable_InitialContext,
+  unstable_RouterContextProvider,
 } from "react-router";
 import {
   init as initEsModuleLexer,
@@ -614,7 +614,7 @@ let reactRouterDevLoadContext: (
   request: Request,
 ) => MaybePromise<
   MiddlewareEnabled extends true
-    ? MaybePromise<unstable_InitialContext | undefined>
+    ? MaybePromise<unstable_RouterContextProvider | undefined>
     : MaybePromise<Record<string, unknown> | undefined>
 > = () => undefined;
 

packages/react-router-express/server.ts

@@ -7,7 +7,7 @@ import type {
   AppLoadContext,
   ServerBuild,
   UNSAFE_MiddlewareEnabled as MiddlewareEnabled,
-  unstable_InitialContext,
+  unstable_RouterContextProvider,
 } from "react-router";
 import { createRequestHandler as createRemixRequestHandler } from "react-router";
 import {
@@ -29,7 +29,7 @@ export type GetLoadContextFunction = (
   req: express.Request,
   res: express.Response,
 ) => MiddlewareEnabled extends true
-  ? MaybePromise<unstable_InitialContext>
+  ? MaybePromise<unstable_RouterContextProvider>
   : MaybePromise<AppLoadContext>;
 
 export type RequestHandler = (