feat(@netlify/vite-plugin-react-router)!: support React Router middleware (#546)

Ultimately, the essence of this change is just to pass an instance of `ReactContextProvider` to the
RR request handler; exporting a `netlifyContextProvider` additionally allows access to Netlify
context in middleware, and the rest is docs and test changes.

It's too much of a hassle to support all the combinations of scenarios if we support earlier
versions where the RR `createContext` and `RouterContextProvider` exports don't exist at all and so
on. Instead, this makes a breaking change that requires 7.9.0+.

fix(deps): move react-router to dev deps

fix(deps): remove unused @react-router/node dep

---------

Co-authored-by: Michal Piechowiak <misiek.piechowiak@gmail.com>

Author: serhalp

packages/vite-plugin-react-router/README.md

@@ -27,3 +27,79 @@ export default defineConfig({
   ],
 })
 ```
+
+### Load context
+
+This plugin automatically includes all
+[Netlify context](https://docs.netlify.com/build/functions/api/#netlify-specific-context-object) fields on loader and
+action context.
+
+If you're using TypeScript, `AppLoadContext` is automatically aware of these fields
+([via module augmentation](https://reactrouter.com/upgrading/remix#9-update-types-for-apploadcontext)).
+
+For example:
+
+```tsx
+import { useLoaderData } from 'react-router'
+import type { Route } from './+types/example'
+
+export async function loader({ context }: Route.LoaderArgs) {
+  return {
+    country: context.geo?.country?.name ?? 'an unknown country',
+  }
+}
+export default function Example() {
+  const { country } = useLoaderData<typeof loader>()
+  return <div>You are visiting from {country}</div>
+}
+```
+
+If you've [opted in to the `future.v8_middleware` flag](https://reactrouter.com/how-to/middleware), you can still use
+the above access pattern for backwards compatibility, but loader and action context will now be an instance of the
+type-safe `RouterContextProvider`. Note that this requires requires v2.0.0+ of `@netlify/vite-plugin-react-router`.
+
+For example:
+
+```tsx
+import { netlifyRouterContext } from '@netlify/vite-plugin-react-router'
+import { useLoaderData } from 'react-router'
+import type { Route } from './+types/example'
+
+export async function loader({ context }: Route.LoaderArgs) {
+  return {
+    country: context.get(netlifyRouterContext).geo?.country?.name ?? 'an unknown country',
+  }
+}
+export default function Example() {
+  const { country } = useLoaderData<typeof loader>()
+  return <div>You are visiting from {country}</div>
+}
+```
+
+### Middleware context
+
+React Router introduced a stable middleware feature in 7.9.0.
+
+To use middleware,
+[opt in to the feature via `future.v8_middleware` and follow the docs](https://reactrouter.com/how-to/middleware). Note
+that this requires requires v2.0.0+ of `@netlify/vite-plugin-react-router`.
+
+To access the [Netlify context](https://docs.netlify.com/build/functions/api/#netlify-specific-context-object)
+specifically, you must import our `RouterContextProvider` instance:
+
+```tsx
+import { netlifyRouterContext } from '@netlify/vite-plugin-react-router'
+
+import type { Route } from './+types/home'
+
+const logMiddleware: Route.MiddlewareFunction = async ({ request, context }) => {
+  const country = context.get(netlifyRouterContext).geo?.country?.name ?? 'unknown'
+  console.log(`Handling ${request.method} request to ${request.url} from ${country}`)
+}
+
+export const middleware: Route.MiddlewareFunction[] = [logMiddleware]
+
+export default function Home() {
+  return <h1>Hello world</h1>
+}
+```

packages/vite-plugin-react-router/package.json

@@ -45,20 +45,20 @@
   },
   "homepage": "https://github.com/netlify/remix-compute#readme",
   "dependencies": {
-    "@react-router/node": "^7.0.1",
-    "isbot": "^5.0.0",
-    "react-router": "^7.0.1"
+    "isbot": "^5.0.0"
   },
   "devDependencies": {
     "@netlify/functions": "^3.1.9",
     "@types/react": "^18.0.27",
     "@types/react-dom": "^18.0.10",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
+    "react-router": "^7.9.4",
     "tsup": "^8.0.2",
     "vite": "^6.2.5"
   },
   "peerDependencies": {
+    "react-router": ">=7.9.0",
     "vite": ">=5.0.0"
   },
   "engines": {

packages/vite-plugin-react-router/src/index.ts

@@ -1,4 +1,4 @@
 export type { GetLoadContextFunction, RequestHandler } from './server'
-export { createRequestHandler } from './server'
+export { createRequestHandler, netlifyRouterContext } from './server'
 
 export { netlifyPlugin as default } from './plugin'

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

@@ -24,7 +24,6 @@ import { createRequestHandler } from "@netlify/vite-plugin-react-router";
 import * as build from "virtual:react-router/server-build";
 export default createRequestHandler({
   build,
-  getLoadContext: async (_req, ctx) => ctx,
 });
 `
 

packages/vite-plugin-react-router/src/server.ts

@@ -1,19 +1,47 @@
 import type { AppLoadContext, ServerBuild } from 'react-router'
-import { createRequestHandler as createReactRouterRequestHandler } from 'react-router'
+import {
+  createContext,
+  RouterContextProvider,
+  createRequestHandler as createReactRouterRequestHandler,
+} from 'react-router'
 import type { Context as NetlifyContext } from '@netlify/functions'
 
-type LoadContext = AppLoadContext & NetlifyContext
+// Augment the user's `AppLoadContext` to include Netlify context fields
+// This is the recommended approach: https://reactrouter.com/upgrading/remix#9-update-types-for-apploadcontext.
+declare module 'react-router' {
+  interface AppLoadContext extends NetlifyContext {}
+}
 
 /**
- * A function that returns the value to use as `context` in route `loader` and
- * `action` functions.
+ * A function that returns the value to use as `context` in route `loader` and `action` functions.
+ *
+ * You can think of this as an escape hatch that allows you to pass environment/platform-specific
+ * values through to your loader/action.
  *
- * You can think of this as an escape hatch that allows you to pass
- * environment/platform-specific values through to your loader/action.
+ * NOTE: v7.9.0 introduced a breaking change when the user opts in to `future.v8_middleware`. This
+ * requires returning an instance of `RouterContextProvider` instead of a plain object. We have a
+ * peer dependency on >=7.9.0 so we can safely *import* these, but we cannot assume the user has
+ * opted in to the flag.
  */
-export type GetLoadContextFunction = (request: Request, context: NetlifyContext) => Promise<LoadContext> | LoadContext
+export type GetLoadContextFunction = GetLoadContextFunction_V7 | GetLoadContextFunction_V8
+export type GetLoadContextFunction_V7 = (
+  request: Request,
+  context: NetlifyContext,
+) => Promise<AppLoadContext> | AppLoadContext
+export type GetLoadContextFunction_V8 = (
+  request: Request,
+  context: NetlifyContext,
+) => Promise<RouterContextProvider> | RouterContextProvider
 
-export type RequestHandler = (request: Request, context: LoadContext) => Promise<Response | void>
+export type RequestHandler = (request: Request, context: NetlifyContext) => Promise<Response>
+
+/**
+ * An instance of `ReactContextProvider` providing access to
+ * [Netlify request context]{@link https://docs.netlify.com/build/functions/api/#netlify-specific-context-object}
+ *
+ * @example context.get(netlifyRouterContext).geo?.country?.name
+ */
+export const netlifyRouterContext = createContext<NetlifyContext>()
 
 /**
  * Given a build and a callback to get the base loader context, this returns
@@ -32,13 +60,26 @@ export function createRequestHandler({
 }): RequestHandler {
   const reactRouterHandler = createReactRouterRequestHandler(build, mode)
 
-  return async (request: Request, netlifyContext: NetlifyContext): Promise<Response | void> => {
+  return async (request: Request, netlifyContext: NetlifyContext): Promise<Response> => {
     const start = Date.now()
     console.log(`[${request.method}] ${request.url}`)
     try {
-      const mergedLoadContext = (await getLoadContext?.(request, netlifyContext)) || netlifyContext
+      const getDefaultReactRouterContext = () => {
+        const ctx = new RouterContextProvider()
+        ctx.set(netlifyRouterContext, netlifyContext)
+
+        // Provide backwards compatibility with previous plain object context
+        // See https://reactrouter.com/how-to/middleware#migration-from-apploadcontext.
+        Object.assign(ctx, netlifyContext)
+
+        return ctx
+      }
+      const reactRouterContext = (await getLoadContext?.(request, netlifyContext)) ?? getDefaultReactRouterContext()
 
-      const response = await reactRouterHandler(request, mergedLoadContext)
+      // @ts-expect-error -- I don't think there's any way to type this properly. We're passing a
+      // union of the two types here, but this function accepts a conditional type based on the
+      // presence of the `future.v8_middleware` flag in the user's config, which we don't have access to.
+      const response = await reactRouterHandler(request, reactRouterContext)
 
       // A useful header for debugging
       response.headers.set('x-nf-runtime', 'Node')