feat(vite-plugin-react-router): add edge support

Author: serhalp

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

@@ -16,6 +16,14 @@
         "types": "./dist/index.d.mts",
         "default": "./dist/index.mjs"
       }
+    },
+    "./function-handler": {
+      "types": "./dist/function-handler.d.mts",
+      "default": "./dist/function-handler.mjs"
+    },
+    "./edge-function-handler": {
+      "types": "./dist/edge-function-handler.d.mts",
+      "default": "./dist/edge-function-handler.mjs"
     }
   },
   "files": [
@@ -26,7 +34,7 @@
   ],
   "scripts": {
     "prepack": "pnpm run build",
-    "build": "tsup-node src/index.ts --format esm,cjs --dts --target node18 --clean",
+    "build": "tsup-node",
     "build:watch": "pnpm run build --watch"
   },
   "repository": {
@@ -48,6 +56,7 @@
     "isbot": "^5.0.0"
   },
   "devDependencies": {
+    "@netlify/edge-functions": "^2.11.0",
     "@netlify/functions": "^3.1.9",
     "@types/react": "^18.0.27",
     "@types/react-dom": "^18.0.10",

packages/vite-plugin-react-router/src/edge-function-handler.ts

@@ -0,0 +1,125 @@
+import type { AppLoadContext, ServerBuild } from 'react-router'
+import {
+  createContext,
+  RouterContextProvider,
+  createRequestHandler as createReactRouterRequestHandler,
+} from 'react-router'
+import type { Context as NetlifyEdgeContext } from '@netlify/edge-functions'
+
+// 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 NetlifyEdgeContext {}
+}
+
+/**
+ * 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.
+ *
+ * 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 = GetLoadContextFunction_V7 | GetLoadContextFunction_V8
+export type GetLoadContextFunction_V7 = (
+  request: Request,
+  context: NetlifyEdgeContext,
+) => Promise<AppLoadContext> | AppLoadContext
+export type GetLoadContextFunction_V8 = (
+  request: Request,
+  context: NetlifyEdgeContext,
+) => Promise<RouterContextProvider> | RouterContextProvider
+
+export type RequestHandler = (request: Request, context: NetlifyEdgeContext) => 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 =
+  // We must use a singleton because Remix contexts rely on referential equality.
+  // We can't hook into the request lifecycle in dev mode, so we use a Proxy to always read from the
+  // current `Netlify.context` value, which is always contextual to the in-flight request.
+  createContext<Partial<NetlifyEdgeContext>>(
+    new Proxy(
+      // Can't reference `Netlify.context` here because it isn't set outside of a request lifecycle
+      {},
+      {
+        get(_target, prop, receiver) {
+          return Reflect.get(Netlify.context ?? {}, prop, receiver)
+        },
+        set(_target, prop, value, receiver) {
+          return Reflect.set(Netlify.context ?? {}, prop, value, receiver)
+        },
+        has(_target, prop) {
+          return Reflect.has(Netlify.context ?? {}, prop)
+        },
+        deleteProperty(_target, prop) {
+          return Reflect.deleteProperty(Netlify.context ?? {}, prop)
+        },
+        ownKeys(_target) {
+          return Reflect.ownKeys(Netlify.context ?? {})
+        },
+        getOwnPropertyDescriptor(_target, prop) {
+          return Reflect.getOwnPropertyDescriptor(Netlify.context ?? {}, prop)
+        },
+      },
+    ),
+  )
+
+/**
+ * Given a build and a callback to get the base loader context, this returns
+ * a Netlify Edge Function handler (https://docs.netlify.com/edge-functions/overview/) which renders the
+ * requested path. The loader context in this lifecycle will contain the Netlify Edge Functions context
+ * fields merged in.
+ */
+export function createRequestHandler({
+  build,
+  mode,
+  getLoadContext,
+}: {
+  build: ServerBuild
+  mode?: string
+  getLoadContext?: GetLoadContextFunction
+}): RequestHandler {
+  const reactRouterHandler = createReactRouterRequestHandler(build, mode)
+
+  return async (request: Request, netlifyContext: NetlifyEdgeContext): Promise<Response> => {
+    const start = Date.now()
+    console.log(`[${request.method}] ${request.url}`)
+    try {
+      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()
+
+      // @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)
+
+      // We can return any React Router response as-is (whether it's a default 404, custom 404,
+      // or any other response) because our edge function's excludedPath config is exhaustive -
+      // static assets are excluded from the edge function entirely, so we never need to fall
+      // through to the CDN.
+      console.log(`[${response.status}] ${request.url} (${Date.now() - start}ms)`)
+      return response
+    } catch (error) {
+      console.error(error)
+
+      return new Response('Internal Error', { status: 500 })
+    }
+  }
+}

packages/vite-plugin-react-router/src/server.ts renamed to packages/vite-plugin-react-router/src/function-handler.ts

@@ -4,12 +4,12 @@ import {
   RouterContextProvider,
   createRequestHandler as createReactRouterRequestHandler,
 } from 'react-router'
-import type { Context as NetlifyContext } from '@netlify/functions'
+import type { Context as NetlifyFunctionContext } from '@netlify/functions'
 
 // 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 {}
+  interface AppLoadContext extends NetlifyFunctionContext {}
 }
 
 /**
@@ -26,14 +26,14 @@ declare module 'react-router' {
 export type GetLoadContextFunction = GetLoadContextFunction_V7 | GetLoadContextFunction_V8
 export type GetLoadContextFunction_V7 = (
   request: Request,
-  context: NetlifyContext,
+  context: NetlifyFunctionContext,
 ) => Promise<AppLoadContext> | AppLoadContext
 export type GetLoadContextFunction_V8 = (
   request: Request,
-  context: NetlifyContext,
+  context: NetlifyFunctionContext,
 ) => Promise<RouterContextProvider> | RouterContextProvider
 
-export type RequestHandler = (request: Request, context: NetlifyContext) => Promise<Response>
+export type RequestHandler = (request: Request, context: NetlifyFunctionContext) => Promise<Response>
 
 /**
  * An instance of `ReactContextProvider` providing access to
@@ -45,7 +45,7 @@ export const netlifyRouterContext =
   // We must use a singleton because Remix contexts rely on referential equality.
   // We can't hook into the request lifecycle in dev mode, so we use a Proxy to always read from the
   // current `Netlify.context` value, which is always contextual to the in-flight request.
-  createContext<Partial<NetlifyContext>>(
+  createContext<Partial<NetlifyFunctionContext>>(
     new Proxy(
       // Can't reference `Netlify.context` here because it isn't set outside of a request lifecycle
       {},
@@ -89,7 +89,7 @@ export function createRequestHandler({
 }): RequestHandler {
   const reactRouterHandler = createReactRouterRequestHandler(build, mode)
 
-  return async (request: Request, netlifyContext: NetlifyContext): Promise<Response> => {
+  return async (request: Request, netlifyContext: NetlifyFunctionContext): Promise<Response> => {
     const start = Date.now()
     console.log(`[${request.method}] ${request.url}`)
     try {
@@ -110,8 +110,6 @@ export function createRequestHandler({
       // 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')
       console.log(`[${response.status}] ${request.url} (${Date.now() - start}ms)`)
       return response
     } catch (error) {

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

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

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

@@ -1,11 +1,21 @@
 import type { Plugin, ResolvedConfig } from 'vite'
-import { mkdir, writeFile } from 'node:fs/promises'
+import { mkdir, writeFile, readdir } from 'node:fs/promises'
 import { join, relative, sep } from 'node:path'
 import { sep as posixSep } from 'node:path/posix'
 import { version, name } from '../package.json'
 
+export interface NetlifyPluginOptions {
+  /**
+   * Deploy to Netlify Edge Functions instead of Netlify Functions.
+   * @default false
+   */
+  edge?: boolean
+}
+
 // https://docs.netlify.com/frameworks-api/#netlify-v1-functions
 const NETLIFY_FUNCTIONS_DIR = '.netlify/v1/functions'
+// https://docs.netlify.com/frameworks-api/#netlify-v1-edge-functions
+const NETLIFY_EDGE_FUNCTIONS_DIR = '.netlify/v1/edge-functions'
 
 const FUNCTION_FILENAME = 'react-router-server.mjs'
 /**
@@ -20,7 +30,16 @@ const toPosixPath = (path: string) => path.split(sep).join(posixSep)
 
 // The virtual module that is the compiled Vite SSR entrypoint (a Netlify Function handler)
 const FUNCTION_HANDLER = /* js */ `
-import { createRequestHandler } from "@netlify/vite-plugin-react-router";
+import { createRequestHandler } from "@netlify/vite-plugin-react-router/function-handler";
+import * as build from "virtual:react-router/server-build";
+export default createRequestHandler({
+  build,
+});
+`
+
+// The virtual module for Edge Functions
+const EDGE_FUNCTION_HANDLER = /* js */ `
+import { createRequestHandler } from "@netlify/vite-plugin-react-router/edge-function-handler";
 import * as build from "virtual:react-router/server-build";
 export default createRequestHandler({
   build,
@@ -42,7 +61,24 @@ function generateNetlifyFunction(handlerPath: string) {
     `
 }
 
-export function netlifyPlugin(): Plugin {
+// This is written to the edge functions directory. It just re-exports
+// the compiled entrypoint, along with Netlify edge function config.
+function generateEdgeFunction(handlerPath: string, excludePath: Array<string> = []) {
+  return /* js */ `
+    export { default } from "${handlerPath}";
+
+    export const config = {
+      name: "React Router server handler",
+      generator: "${name}@${version}",
+      cache: "manual",
+      path: "/*",
+      excludedPath: ${JSON.stringify(excludePath)},
+    };
+    `
+}
+
+export function netlifyPlugin(options: NetlifyPluginOptions = {}): Plugin {
+  const { edge = false } = options
   let resolvedConfig: ResolvedConfig
   let isProductionSsrBuild = false
   return {
@@ -65,6 +101,24 @@ export function netlifyPlugin(): Plugin {
           config.build.rollupOptions.output = {}
         }
         config.build.rollupOptions.output.entryFileNames = '[name].js'
+
+        // Configure for Edge Functions if enabled
+        if (edge) {
+          config.ssr = {
+            ...config.ssr,
+            target: 'webworker',
+            // Only externalize Node builtins
+            noExternal: /^(?!node:).*$/,
+            resolve: {
+              conditions: ['worker', 'deno', 'browser'],
+              externalConditions: ['worker', 'deno'],
+            },
+          }
+          config.resolve = {
+            ...config.resolve,
+            conditions: ['worker', 'deno', ...(config.resolve?.conditions || [])],
+          }
+        }
       }
     },
     async resolveId(source) {
@@ -75,24 +129,44 @@ export function netlifyPlugin(): Plugin {
     // See https://vitejs.dev/guide/api-plugin#virtual-modules-convention.
     load(id) {
       if (id === RESOLVED_FUNCTION_HANDLER_MODULE_ID) {
-        return FUNCTION_HANDLER
+        return edge ? EDGE_FUNCTION_HANDLER : FUNCTION_HANDLER
       }
     },
     async configResolved(config) {
       resolvedConfig = config
     },
     // See https://rollupjs.org/plugin-development/#writebundle.
     async writeBundle() {
-      // Write the server entrypoint to the Netlify functions directory
       if (isProductionSsrBuild) {
-        const functionsDirectory = join(resolvedConfig.root, NETLIFY_FUNCTIONS_DIR)
-
-        await mkdir(functionsDirectory, { recursive: true })
-
         const handlerPath = join(resolvedConfig.build.outDir, `${FUNCTION_HANDLER_CHUNK}.js`)
-        const relativeHandlerPath = toPosixPath(relative(functionsDirectory, handlerPath))
 
-        await writeFile(join(functionsDirectory, FUNCTION_FILENAME), generateNetlifyFunction(relativeHandlerPath))
+        if (edge) {
+          // Edge Functions do not have a `preferStatic` option, so we must exhaustively exclude
+          // static files to serve them from the CDN without compute.
+          // RR7's build out dir contains /server and /client subdirectories. This is documented and
+          // not configurable, so the client out dir is always at ../client from the server out dir.
+          const clientDir = join(resolvedConfig.build.outDir, '..', 'client')
+          const entries = await readdir(clientDir, { withFileTypes: true })
+          const excludePath = [
+            '/.netlify/*',
+            ...entries.map((entry) => (entry.isDirectory() ? `/${entry.name}/*` : `/${entry.name}`)),
+          ]
+
+          // Write the server entry point to the Netlify Edge Functions directory
+          const edgeFunctionsDir = join(resolvedConfig.root, NETLIFY_EDGE_FUNCTIONS_DIR)
+          await mkdir(edgeFunctionsDir, { recursive: true })
+          const relativeHandlerPath = toPosixPath(relative(edgeFunctionsDir, handlerPath))
+          await writeFile(
+            join(edgeFunctionsDir, FUNCTION_FILENAME),
+            generateEdgeFunction(relativeHandlerPath, excludePath),
+          )
+        } else {
+          // Write the server entry point to the Netlify Functions directory
+          const functionsDir = join(resolvedConfig.root, NETLIFY_FUNCTIONS_DIR)
+          await mkdir(functionsDir, { recursive: true })
+          const relativeHandlerPath = toPosixPath(relative(functionsDir, handlerPath))
+          await writeFile(join(functionsDir, FUNCTION_FILENAME), generateNetlifyFunction(relativeHandlerPath))
+        }
       }
     },
   }

packages/vite-plugin-react-router/tsup.config.ts

@@ -0,0 +1,23 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig([
+  {
+    entry: ['src/index.ts'],
+    format: ['esm', 'cjs'],
+    dts: true,
+    target: 'node18',
+    clean: true,
+  },
+  {
+    entry: ['src/function-handler.ts'],
+    format: ['esm'],
+    dts: true,
+    target: 'node18',
+  },
+  {
+    entry: ['src/edge-function-handler.ts'],
+    format: ['esm'],
+    dts: true,
+    target: 'node18',
+  },
+])