fix: populate value for Netlify RR context in dev

Follow-up to #546.

Since the `netlifyRouterContext.set()` call was occurring in the server entry point built for
production but not in dev, and no default value was set for the context at construction time, using
middleware in dev would throw.

There's no ergonomic way to set up a `.set()` call dynamically on a context in dev, as far as I can
tell. This leaves the default value set at construction time as our only option.

To make this work, we can use the global `Netlify.context`. However, this is only accessible during
a request-response lifecycle, not in module scope at module init time. So this commit simply changes
`netlifyRouterContext` to a function `getNetlifyRouterContext()` so that we can lazily construct the
context with a default value of `Netlify.context` during a request lifecycle.

To be clear, the Netlify router context will only work in local dev when using either the Netlify
CLI or `@netlify/vite-plugin`.

Author: serhalp

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

@@ -3,27 +3,37 @@
 The React Router Adapter for Netlify allows you to deploy your [React Router](https://reactrouter.com) app to
 [Netlify Functions](https://docs.netlify.com/functions/overview/).
 
-To deploy a React Router 7+ site to Netlify, install this package:
-
 ## How to use
 
+To deploy a React Router 7+ site to Netlify, install this package:
+
 ```sh
 npm install --save-dev @netlify/vite-plugin-react-router
 ```
 
+It's also recommended (but not required) to use the
+[Netlify Vite plugin](https://www.npmjs.com/package/@netlify/vite-plugin), which provides full Netlify platform
+emulation directly in your local dev server:
+
+```sh
+npm install --save-dev @netlify/vite-plugin
+```
+
 and include the Netlify plugin in your `vite.config.ts`:
 
 ```typescript
 import { reactRouter } from '@react-router/dev/vite'
 import { defineConfig } from 'vite'
 import tsconfigPaths from 'vite-tsconfig-paths'
-import netlifyPlugin from '@netlify/vite-plugin-react-router' // <- add this
+import netlifyReactRouter from '@netlify/vite-plugin-react-router' // <- add this
+import netlify from '@netlify/vite-plugin' // <- add this (optional)
 
 export default defineConfig({
   plugins: [
     reactRouter(),
     tsconfigPaths(),
-    netlifyPlugin(), // <- add this
+    netlifyReactRouter(), // <- add this
+    netlify(), // <- add this (optional)
   ],
 })
 ```
@@ -61,13 +71,13 @@ type-safe `RouterContextProvider`. Note that this requires requires v2.0.0+ of `
 For example:
 
 ```tsx
-import { netlifyRouterContext } from '@netlify/vite-plugin-react-router'
+import { getNetlifyRouterContext } 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',
+    country: context.get(getNetlifyRouterContext()).geo?.country?.name ?? 'an unknown country',
   }
 }
 export default function Example() {
@@ -76,6 +86,10 @@ export default function Example() {
 }
 ```
 
+> [!IMPORTANT] Note that in local development, `getNetlifyRouterContext` requires Netlify platform emulation, which is
+> provided seamlessly by [`@netlify/vite-plugin`](https://www.npmjs.com/package/@netlify/vite-plugin) (or Netlify CLI -
+> up to you).
+
 ### Middleware context
 
 React Router introduced a stable middleware feature in 7.9.0.
@@ -88,12 +102,12 @@ To access the [Netlify context](https://docs.netlify.com/build/functions/api/#ne
 specifically, you must import our `RouterContextProvider` instance:
 
 ```tsx
-import { netlifyRouterContext } from '@netlify/vite-plugin-react-router'
+import { getNetlifyRouterContext } 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'
+  const country = context.get(getNetlifyRouterContext()).geo?.country?.name ?? 'unknown'
   console.log(`Handling ${request.method} request to ${request.url} from ${country}`)
 }
 
@@ -103,3 +117,7 @@ export default function Home() {
   return <h1>Hello world</h1>
 }
 ```
+
+> [!IMPORTANT] Note that in local development, `getNetlifyRouterContext` requires Netlify platform emulation, which is
+> provided seamlessly by [`@netlify/vite-plugin`](https://www.npmjs.com/package/@netlify/vite-plugin) (or Netlify CLI -
+> up to you).

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

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

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

@@ -1,4 +1,4 @@
-import type { AppLoadContext, ServerBuild } from 'react-router'
+import type { AppLoadContext, RouterContext, ServerBuild } from 'react-router'
 import {
   createContext,
   RouterContextProvider,
@@ -35,13 +35,20 @@ export type GetLoadContextFunction_V8 = (
 
 export type RequestHandler = (request: Request, context: NetlifyContext) => Promise<Response>
 
+let netlifyRouterContext: RouterContext<Partial<NetlifyContext>>
 /**
  * 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
+ * @example context.get(getNetlifyRouterContext()).geo?.country?.name
  */
-export const netlifyRouterContext = createContext<NetlifyContext>()
+export const getNetlifyRouterContext = () => {
+  // We must use a singleton because Remix contexts rely on referential equality
+  // We defer initialization until first use so that we can initialize it with a default value
+  // within a request lifecycle, where the `Netlify` global will be set. This is just for dev.
+  netlifyRouterContext ??= createContext<Partial<NetlifyContext>>(Netlify.context ?? {})
+  return netlifyRouterContext
+}
 
 /**
  * Given a build and a callback to get the base loader context, this returns
@@ -66,7 +73,7 @@ export function createRequestHandler({
     try {
       const getDefaultReactRouterContext = () => {
         const ctx = new RouterContextProvider()
-        ctx.set(netlifyRouterContext, netlifyContext)
+        ctx.set(getNetlifyRouterContext(), netlifyContext)
 
         // Provide backwards compatibility with previous plain object context
         // See https://reactrouter.com/how-to/middleware#migration-from-apploadcontext.

tests/e2e/fixtures/react-router-v8-middleware/app/routes/context.tsx

@@ -1,11 +1,11 @@
-import { netlifyRouterContext } from '@netlify/vite-plugin-react-router'
+import { getNetlifyRouterContext } from '@netlify/vite-plugin-react-router'
 import { useLoaderData } from 'react-router'
 
 import type { Route } from './+types/context'
 
 export async function loader({ context }: Route.LoaderArgs) {
   return {
-    siteName: context.get(netlifyRouterContext).site.name,
+    siteName: context.get(getNetlifyRouterContext()).site.name,
   }
 }
 export default function About() {

tests/e2e/fixtures/react-router-v8-middleware/app/routes/middleware.tsx

@@ -1,9 +1,9 @@
-import { netlifyRouterContext } from '@netlify/vite-plugin-react-router'
+import { getNetlifyRouterContext } from '@netlify/vite-plugin-react-router'
 
 import type { Route } from './+types/middleware'
 
 const logMiddleware: Route.MiddlewareFunction = async ({ request, context }, next) => {
-  const siteName = context.get(netlifyRouterContext).site.name
+  const siteName = context.get(getNetlifyRouterContext()).site.name
   console.log(`Handling ${request.method} request to ${request.url} on ${siteName}`)
   const response = await next()
   response.headers.set('x-test-site-name', siteName)