fix(@netlify/vite-plugin-react-router): fix local dev with edge: true (#572)

serhalp · web-flow · commit dfb27c1cb52d · 2025-11-06T15:02:00.000Z
* fix(deps): bump isbot

because why not

* fix(deps): move incorrect dev deps to prod deps

These are now needed at runtime when importing `netlifyRouterContext`.

* fix: fix local dev in edge mode

There's some more sophisticated solution involving the Vite Environment API down the line, but for
now I just ported something very similar to what we do for Remix: have users write a one-liner
server entry to uses our Vite virtual module that conditionally resolves depending on build (edge
entry) vs. dev (node.js entry).

As a bonus, the file for users to copy is a single line instead of 40.
diff --git a/packages/vite-plugin-react-router/README.md b/packages/vite-plugin-react-router/README.md
@@ -58,59 +58,23 @@ export default defineConfig({
 })
 ```
 
-Second, you **must** provide an `app/entry.server.tsx` (or `.jsx`) file that uses web-standard APIs compatible with the
-Deno runtime. Create a file with the following content:
-
-> [!IMPORTANT]
->
-> This file uses `renderToReadableStream` (Web Streams API) instead of `renderToPipeableStream` (Node.js API), which is
-> required for the Deno runtime. You may customize your server entry file, but see below for important edge runtime
-> constraints.
+Second, you **must** provide an `app/entry.server.tsx` (or `.jsx`) file. Create a file with the following content:
 
 ```tsx
-import type { AppLoadContext, EntryContext } from 'react-router'
-import { ServerRouter } from 'react-router'
-import { isbot } from 'isbot'
-import { renderToReadableStream } from 'react-dom/server'
-
-export default async function handleRequest(
-  request: Request,
-  responseStatusCode: number,
-  responseHeaders: Headers,
-  routerContext: EntryContext,
-  _loadContext: AppLoadContext,
-) {
-  let shellRendered = false
-  const userAgent = request.headers.get('user-agent')
-
-  const body = await renderToReadableStream(<ServerRouter context={routerContext} url={request.url} />, {
-    onError(error: unknown) {
-      responseStatusCode = 500
-      // Log streaming rendering errors from inside the shell.  Don't log
-      // errors encountered during initial shell rendering since they'll
-      // reject and get logged in handleDocumentRequest.
-      if (shellRendered) {
-        console.error(error)
-      }
-    },
-  })
-  shellRendered = true
-
-  // Ensure requests from bots and SPA Mode renders wait for all content to load before responding
-  // https://react.dev/reference/react-dom/server/renderToPipeableStream#waiting-for-all-content-to-load-for-crawlers-and-static-generation
-  if ((userAgent && isbot(userAgent)) || routerContext.isSpaMode) {
-    await body.allReady
-  }
-
-  responseHeaders.set('Content-Type', 'text/html')
-  return new Response(body, {
-    headers: responseHeaders,
-    status: responseStatusCode,
-  })
-}
+export { default } from 'virtual:netlify-server-entry'
 ```
 
-You may need to `npm install isbot` if you do not have this dependency.
+> [!TIP]
+>
+> If you prefer to avoid a `@ts-ignore` here, add this to `vite-env.d.ts` in your project root (or anywhere you prefer):
+>
+> ```typescript
+> declare module 'virtual:netlify-server-entry' {
+>   import type { ServerEntryModule } from 'react-router'
+>   const entry: ServerEntryModule
+>   export default entry
+> }
+> ```
 
 Finally, if you have your own Netlify Functions (typically in `netlify/functions`) for which you've configured a `path`,
 you must exclude those paths to avoid conflicts with the generated React Router SSR handler:
diff --git a/packages/vite-plugin-react-router/package.json b/packages/vite-plugin-react-router/package.json
@@ -24,6 +24,10 @@
     "./edge": {
       "types": "./dist/edge.d.mts",
       "default": "./dist/edge.mjs"
+    },
+    "./entry.server.edge": {
+      "types": "./dist/entry.server.edge.d.mts",
+      "default": "./dist/entry.server.edge.mjs"
     }
   },
   "files": [
@@ -54,11 +58,11 @@
   },
   "homepage": "https://github.com/netlify/remix-compute#readme",
   "dependencies": {
-    "isbot": "^5.0.0"
-  },
-  "devDependencies": {
     "@netlify/edge-functions": "^3.0.2",
     "@netlify/functions": "^5.1.0",
+    "isbot": "^5.1.25"
+  },
+  "devDependencies": {
     "@types/react": "^18.0.27",
     "@types/react-dom": "^18.0.10",
     "react": "^18.2.0",
diff --git a/packages/vite-plugin-react-router/src/entry.server.edge.tsx b/packages/vite-plugin-react-router/src/entry.server.edge.tsx
@@ -0,0 +1,55 @@
+import type { AppLoadContext, EntryContext } from 'react-router'
+import { ServerRouter } from 'react-router'
+import { isbot } from 'isbot'
+import { renderToReadableStream } from 'react-dom/server'
+
+/**
+ * Edge-compatible server entry using Web Streams instead of Node.js Streams.
+ * @see {@link https://reactrouter.com/api/framework-conventions/entry.server.tsx}
+ *
+ * This file was copied as-is from the React Router repository.
+ * @see {@link
+ * https://github.com/remix-run/react-router/blob/cb9a090316003988ff367bb2f2d1ef5bd03bd3af/integration/helpers/vite-plugin-cloudflare-template/app/entry.server.tsx}
+ *
+ *
+ * @example Export this from your `app/entry.server.tsx` when using `edge: true`:
+ *
+ * ```tsx
+ * export { default } from 'virtual:netlify-server-entry'
+ * ```
+ */
+export default async function handleRequest(
+  request: Request,
+  responseStatusCode: number,
+  responseHeaders: Headers,
+  routerContext: EntryContext,
+  _loadContext: AppLoadContext,
+) {
+  let shellRendered = false
+  const userAgent = request.headers.get('user-agent')
+
+  const body = await renderToReadableStream(<ServerRouter context={routerContext} url={request.url} />, {
+    onError(error: unknown) {
+      responseStatusCode = 500
+      // Log streaming rendering errors from inside the shell.  Don't log
+      // errors encountered during initial shell rendering since they'll
+      // reject and get logged in handleDocumentRequest.
+      if (shellRendered) {
+        console.error(error)
+      }
+    },
+  })
+  shellRendered = true
+
+  // Ensure requests from bots and SPA Mode renders wait for all content to load before responding
+  // https://react.dev/reference/react-dom/server/renderToPipeableStream#waiting-for-all-content-to-load-for-crawlers-and-static-generation
+  if ((userAgent && isbot(userAgent)) || routerContext.isSpaMode) {
+    await body.allReady
+  }
+
+  responseHeaders.set('Content-Type', 'text/html')
+  return new Response(body, {
+    headers: responseHeaders,
+    status: responseStatusCode,
+  })
+}
diff --git a/packages/vite-plugin-react-router/src/plugin.ts b/packages/vite-plugin-react-router/src/plugin.ts
@@ -1,5 +1,5 @@
 import { mkdir, writeFile, readdir } from 'node:fs/promises'
-import { join, relative, sep } from 'node:path'
+import { dirname, join, relative, resolve, sep } from 'node:path'
 import { sep as posixSep } from 'node:path/posix'
 
 import type { Plugin, ResolvedConfig } from 'vite'
@@ -38,6 +38,8 @@ const FUNCTION_HANDLER_CHUNK = 'server'
 const FUNCTION_HANDLER_MODULE_ID = 'virtual:netlify-server'
 const RESOLVED_FUNCTION_HANDLER_MODULE_ID = `\0${FUNCTION_HANDLER_MODULE_ID}`
 
+const SERVER_ENTRY_MODULE_ID = 'virtual:netlify-server-entry'
+
 const toPosixPath = (path: string) => path.split(sep).join(posixSep)
 
 // The virtual module that is the compiled Vite SSR entrypoint (a Netlify Function handler)
@@ -95,9 +97,11 @@ export function netlifyPlugin(options: NetlifyPluginOptions = {}): Plugin {
   const additionalExcludedPaths = options.excludedPaths ?? []
   let resolvedConfig: ResolvedConfig
   let isProductionSsrBuild = false
+  let currentCommand: 'build' | 'serve' | undefined
   return {
     name: 'vite-plugin-netlify-react-router',
     config(config, { command, isSsrBuild }) {
+      currentCommand = command
       isProductionSsrBuild = isSsrBuild === true && command === 'build'
       if (isProductionSsrBuild) {
         // Replace the default SSR entrypoint with our own entrypoint (which is imported by our
@@ -132,10 +136,26 @@ export function netlifyPlugin(options: NetlifyPluginOptions = {}): Plugin {
         }
       }
     },
-    async resolveId(source) {
+    async resolveId(source, importer, options) {
       if (source === FUNCTION_HANDLER_MODULE_ID) {
         return RESOLVED_FUNCTION_HANDLER_MODULE_ID
       }
+
+      // Conditionally resolve the server entry based on the command and runtime.
+      // Users will export from 'virtual:netlify-server-entry' in their `app/entry.server.tsx`
+      //
+      if (source === SERVER_ENTRY_MODULE_ID && edge) {
+        if (currentCommand === 'serve') {
+          // Dev mode with edge runtime: use the default Node.js-compatible entry
+          const reactRouterDev = await this.resolve('@react-router/dev/config', importer, options)
+          if (!reactRouterDev) {
+            throw new Error('The @react-router/dev package is required for local development. Please install it.')
+          }
+          return resolve(dirname(reactRouterDev.id), 'config/defaults/entry.server.node.tsx')
+        }
+        // Production build with edge runtime: use our edge-compatible entry
+        return this.resolve('@netlify/vite-plugin-react-router/entry.server.edge', importer, options)
+      }
     },
     // See https://vitejs.dev/guide/api-plugin#virtual-modules-convention.
     load(id) {
diff --git a/packages/vite-plugin-react-router/tsup.config.ts b/packages/vite-plugin-react-router/tsup.config.ts
@@ -6,6 +6,7 @@ export default defineConfig([
       index: 'src/index.ts',
       serverless: 'src/runtimes/netlify-functions.ts',
       edge: 'src/runtimes/netlify-edge-functions.ts',
+      'entry.server.edge': 'src/entry.server.edge.tsx',
     },
     format: ['esm'],
     dts: true,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/tests/e2e/fixtures/react-router-edge-site/app/entry.server.tsx b/tests/e2e/fixtures/react-router-edge-site/app/entry.server.tsx
@@ -1,40 +1 @@
-import type { AppLoadContext, EntryContext } from 'react-router'
-import { ServerRouter } from 'react-router'
-import { isbot } from 'isbot'
-import { renderToReadableStream } from 'react-dom/server'
-
-export default async function handleRequest(
-  request: Request,
-  responseStatusCode: number,
-  responseHeaders: Headers,
-  routerContext: EntryContext,
-  _loadContext: AppLoadContext,
-) {
-  let shellRendered = false
-  const userAgent = request.headers.get('user-agent')
-
-  const body = await renderToReadableStream(<ServerRouter context={routerContext} url={request.url} />, {
-    onError(error: unknown) {
-      responseStatusCode = 500
-      // Log streaming rendering errors from inside the shell.  Don't log
-      // errors encountered during initial shell rendering since they'll
-      // reject and get logged in handleDocumentRequest.
-      if (shellRendered) {
-        console.error(error)
-      }
-    },
-  })
-  shellRendered = true
-
-  // Ensure requests from bots and SPA Mode renders wait for all content to load before responding
-  // https://react.dev/reference/react-dom/server/renderToPipeableStream#waiting-for-all-content-to-load-for-crawlers-and-static-generation
-  if ((userAgent && isbot(userAgent)) || routerContext.isSpaMode) {
-    await body.allReady
-  }
-
-  responseHeaders.set('Content-Type', 'text/html')
-  return new Response(body, {
-    headers: responseHeaders,
-    status: responseStatusCode,
-  })
-}
+export { default } from 'virtual:netlify-server-entry'
diff --git a/tests/e2e/fixtures/react-router-edge-v8-middleware/app/entry.server.tsx b/tests/e2e/fixtures/react-router-edge-v8-middleware/app/entry.server.tsx
@@ -1,40 +1 @@
-import type { AppLoadContext, EntryContext } from 'react-router'
-import { ServerRouter } from 'react-router'
-import { isbot } from 'isbot'
-import { renderToReadableStream } from 'react-dom/server'
-
-export default async function handleRequest(
-  request: Request,
-  responseStatusCode: number,
-  responseHeaders: Headers,
-  routerContext: EntryContext,
-  _loadContext: AppLoadContext,
-) {
-  let shellRendered = false
-  const userAgent = request.headers.get('user-agent')
-
-  const body = await renderToReadableStream(<ServerRouter context={routerContext} url={request.url} />, {
-    onError(error: unknown) {
-      responseStatusCode = 500
-      // Log streaming rendering errors from inside the shell.  Don't log
-      // errors encountered during initial shell rendering since they'll
-      // reject and get logged in handleDocumentRequest.
-      if (shellRendered) {
-        console.error(error)
-      }
-    },
-  })
-  shellRendered = true
-
-  // Ensure requests from bots and SPA Mode renders wait for all content to load before responding
-  // https://react.dev/reference/react-dom/server/renderToPipeableStream#waiting-for-all-content-to-load-for-crawlers-and-static-generation
-  if ((userAgent && isbot(userAgent)) || routerContext.isSpaMode) {
-    await body.allReady
-  }
-
-  responseHeaders.set('Content-Type', 'text/html')
-  return new Response(body, {
-    headers: responseHeaders,
-    status: responseStatusCode,
-  })
-}
+export { default } from 'virtual:netlify-server-entry'
