Use runtime-specific default server entries (#15290)

* Use runtime-specific default server entries

Assisted-By: devx/e4d8ffad-97c4-40b6-9373-8114dbad5591

* Add readable stream future flag for Node defaults

* Split Node readable stream future flag change file

* Mark Node readable stream flag change as unstable

* Clarify Node readable stream future flag docs

* Update

Assisted-By: devx/e4d8ffad-97c4-40b6-9373-8114dbad5591

* Update Node readable stream change note

* Fix e2e tests

Assisted-By: devx/e4d8ffad-97c4-40b6-9373-8114dbad5591

Author: brophdawg11

docs/upgrading/future.md

@@ -46,6 +46,39 @@ _No known planned breaking changes yet_
 
 We document some [unstable] flags here as a reference for folks contributing to the project via beta testing, but they are not generally recommended for production use and may have breaking changes in patch or minor releases - adopt with caution!
 
+### `future.unstable_enableNodeReadableStream`
+
+[MODES: framework]
+
+<br/>
+<br/>
+
+**Background**
+
+Now that the Web Streams API is [stable](https://nodejs.org/docs/latest-v22.x/api/webstreams.html) in Node 22+, it's viable for React Router to use React's [`renderToReadableStream`](https://react.dev/reference/react-dom/server/renderToReadableStream) in the server entry.
+
+When no `entry.server.tsx` file is present, React Router defaults to [`renderToPipeableStream`](https://react.dev/reference/react-dom/server/renderToPipeableStream) when a Node runtime is detected, and `renderToReadableStream` otherwise.
+
+With this flag enabled, React Router will default to `renderToReadableStream` on all runtimes, including Node. You can continue to use `renderToPipeableStream` via a custom `entry.server.tsx` file if needed.
+
+<docs-info>Enabling this flag might even provide slight performance gains because we are already using Web Streams internally, so this flag removes some unnecessary transforms between Web and Node streams.</docs-info>
+
+👉 **Enable the Flag**
+
+```ts filename=react-router.config.ts
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  future: {
+    unstable_enableNodeReadableStream: true,
+  },
+} satisfies Config;
+```
+
+**Update your Code**
+
+No code changes are required. If your app has a custom `entry.server.tsx`, this flag will not change your runtime behavior.
+
 ### `future.unstable_optimizeDeps`
 
 [MODES: framework]

integration/cli-test.ts

@@ -4,6 +4,7 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
+  readFileSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
@@ -15,7 +16,7 @@ import { expect, test } from "@playwright/test";
 import dedent from "dedent";
 import semver from "semver";
 
-import { createProject } from "./helpers/vite";
+import { build, createProject, reactRouterConfig } from "./helpers/vite";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const rootDirectory = path.resolve(__dirname, "..");
@@ -198,6 +199,51 @@ test.describe("cli", () => {
 
       expect(existsSync(entryServerFile)).toBeTruthy();
       expect(existsSync(entryClientFile)).toBeTruthy();
+      expect(readFileSync(entryServerFile, "utf-8")).toContain(
+        "renderToPipeableStream",
+      );
+    });
+
+    test("generates a web server entry for non-Node projects", async () => {
+      const cwd = await createProject();
+      let packageJsonPath = path.join(cwd, "package.json");
+      let pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+      delete pkg.dependencies["@react-router/express"];
+      delete pkg.dependencies["@react-router/node"];
+      delete pkg.dependencies["@react-router/serve"];
+      writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2));
+
+      let entryServerFile = path.join(cwd, "app", "entry.server.tsx");
+
+      expect(existsSync(entryServerFile)).toBeFalsy();
+
+      run(["reveal", "entry.server"], { cwd });
+
+      expect(existsSync(entryServerFile)).toBeTruthy();
+      expect(readFileSync(entryServerFile, "utf-8")).toContain(
+        "renderToReadableStream",
+      );
+    });
+
+    test("generates a web server entry for Node projects with the readable stream future flag", async () => {
+      const cwd = await createProject({
+        "react-router.config.ts": reactRouterConfig({
+          future: {
+            unstable_enableNodeReadableStream: true,
+          },
+        }),
+      });
+
+      let entryServerFile = path.join(cwd, "app", "entry.server.tsx");
+
+      expect(existsSync(entryServerFile)).toBeFalsy();
+
+      run(["reveal", "entry.server"], { cwd });
+
+      expect(existsSync(entryServerFile)).toBeTruthy();
+      expect(readFileSync(entryServerFile, "utf-8")).toContain(
+        "renderToReadableStream",
+      );
     });
 
     test("rsc generates entry.{ssr,rsc,client}.tsx in the app directory", async () => {
@@ -250,4 +296,18 @@ test.describe("cli", () => {
       expect(existsSync(entryClientFile)).toBeTruthy();
     });
   });
+
+  test("builds a Node project with the readable stream future flag and default server entry", async () => {
+    const cwd = await createProject({
+      "react-router.config.ts": reactRouterConfig({
+        future: {
+          unstable_enableNodeReadableStream: true,
+        },
+      }),
+    });
+
+    const buildResult = build({ cwd });
+
+    expect(buildResult.status).toBe(0);
+  });
 });

integration/vite-plugin-cloudflare-test.ts

@@ -2,7 +2,13 @@ import { expect } from "@playwright/test";
 import dedent from "dedent";
 import getPort from "get-port";
 
-import { type Files, test, viteConfig } from "./helpers/vite.js";
+import {
+  build,
+  createProject,
+  type Files,
+  test,
+  viteConfig,
+} from "./helpers/vite.js";
 
 const tsx = dedent;
 const css = dedent;
@@ -177,4 +183,16 @@ test.describe("vite-plugin-cloudflare", () => {
       "20px",
     );
   });
+
+  test("builds project with default server entry", async () => {
+    const files = defineFiles();
+    const cwd = await createProject(
+      await files({ port: 0 }),
+      "vite-plugin-cloudflare-template",
+    );
+
+    const buildResult = build({ cwd });
+
+    expect(buildResult.status).toBe(0);
+  });
 });

integration/vite-presets-test.ts

@@ -246,6 +246,7 @@ test.describe("Vite / presets", async () => {
 
       // Ensure future flags from presets are properly merged
       expect(buildEndArgsMeta.futureFlags).toEqual({
+        unstable_enableNodeReadableStream: false,
         unstable_optimizeDeps: true,
       });
       expect(buildEndArgsMeta.splitRouteModules).toBe(true);

packages/react-router-dev/.changes/minor.default-server-entry-runtime.md

@@ -0,0 +1,5 @@
+Add a web streams default server entry for non-Node Framework mode apps
+
+- Apps using `@react-router/node`, `@react-router/express`, or `@react-router/serve` continue to use the `renderToPipeableStream` default server entry
+- Apps without those Node server adapter dependencies use a `renderToReadableStream` default server entry
+- Non-Node apps with their own `entry.server.tsx` may be able to remove it in favor of the default if it is not doing anything custom

packages/react-router-dev/.changes/unstable.node-readable-stream-future-flag.md

@@ -0,0 +1,3 @@
+Add a new [`future.unstable_enableNodeReadableStream`](https://reactrouter.com/upgrading/future#futureunstable_enablenodereadablestream) flag to opt Node Framework mode apps into using `renderToReadableStream` instead of `renderToPipeableStream`
+
+- This flag has no effect if you have your own `entry.server.tsx`

packages/react-router-dev/cli/commands.ts

@@ -10,7 +10,7 @@ import "react-router";
 
 import type { ViteDevOptions } from "../vite/dev";
 import type { ViteBuildOptions } from "../vite/build";
-import { loadConfig } from "../config/config";
+import { hasNodeDependency, loadConfig } from "../config/config";
 import { formatRoutes } from "../config/format";
 import type { RoutesFormat } from "../config/format";
 import { transpile as convertFileToJS } from "./useJavascript";
@@ -171,12 +171,6 @@ export async function generateEntry(
     await copyFile(defaultEntry, outputFile);
   } else {
     let pkgJson = await readPackageJSON(rootDirectory);
-    let deps = pkgJson.dependencies ?? {};
-
-    if (!deps["@react-router/node"]) {
-      console.error(colors.red(`No default server entry detected.`));
-      return;
-    }
 
     let defaultEntryClient = path.resolve(
       defaultsDirectory,
@@ -185,7 +179,10 @@ export async function generateEntry(
 
     let defaultEntryServer = path.resolve(
       defaultsDirectory,
-      `entry.server.node.tsx`,
+      hasNodeDependency(pkgJson.dependencies) &&
+        !configResult.value.future.unstable_enableNodeReadableStream
+        ? `entry.server.node.tsx`
+        : `entry.server.web.tsx`,
     );
 
     let isServerEntry = entry === "entry.server";

packages/react-router-dev/config/config.ts

@@ -8,7 +8,12 @@ import chokidar, {
   type FSWatcher,
   type EmitArgs as ChokidarEmitArgs,
 } from "chokidar";
-import { readPackageJSON, sortPackage, updatePackage } from "pkg-types";
+import {
+  readPackageJSON,
+  sortPackage,
+  updatePackage,
+  type PackageJson,
+} from "pkg-types";
 import colors from "picocolors";
 import pick from "lodash/pick.js";
 import omit from "lodash/omit.js";
@@ -89,6 +94,7 @@ type ServerModuleFormat = "esm" | "cjs";
 type ValidateConfigFunction = (config: ReactRouterConfig) => string | void;
 
 interface FutureConfig {
+  unstable_enableNodeReadableStream: boolean;
   unstable_optimizeDeps: boolean;
 }
 
@@ -738,6 +744,8 @@ async function resolveConfig({
   }
 
   let future: FutureConfig = {
+    unstable_enableNodeReadableStream:
+      userAndPresetConfigs.future?.unstable_enableNodeReadableStream ?? false,
     unstable_optimizeDeps:
       userAndPresetConfigs.future?.unstable_optimizeDeps ?? false,
   };
@@ -1045,12 +1053,6 @@ export async function resolveEntryFiles({
     let pkgJson = await readPackageJSON(packageJsonDirectory);
     let deps = pkgJson.dependencies ?? {};
 
-    if (!deps["@react-router/node"]) {
-      throw new Error(
-        `Could not determine server runtime. Please install @react-router/node, or provide a custom entry.server.tsx/jsx file in your app directory.`,
-      );
-    }
-
     if (!deps["isbot"]) {
       console.log(
         "adding `isbot@5` to your package.json, you should commit this change",
@@ -1070,7 +1072,11 @@ export async function resolveEntryFiles({
       });
     }
 
-    entryServerFile = `entry.server.node.tsx`;
+    entryServerFile =
+      hasNodeDependency(deps) &&
+      !reactRouterConfig.future.unstable_enableNodeReadableStream
+        ? `entry.server.node.tsx`
+        : `entry.server.web.tsx`;
   }
 
   let entryClientFilePath = userEntryClientFile
@@ -1127,6 +1133,19 @@ function omitRoutes(
 
 const entryExts = [".js", ".jsx", ".ts", ".tsx", ".mjs", ".mts"];
 
+export function hasNodeDependency(deps: PackageJson["dependencies"]) {
+  // Match the server condition check in the Vite plugin: missing dependencies
+  // imply Node for backwards compatibility.
+  return (
+    !deps ||
+    Boolean(
+      deps["@react-router/node"] ||
+      deps["@react-router/express"] ||
+      deps["@react-router/serve"],
+    )
+  );
+}
+
 function isEntryFile(entryBasename: string, filename: string) {
   return entryExts.some((ext) => filename === `${entryBasename}${ext}`);
 }

…cloudflare-template/app/entry.server.tsx …dev/config/defaults/entry.server.web.tsxintegration/helpers/vite-plugin-cloudflare-template/app/entry.server.tsx renamed to packages/react-router-dev/config/defaults/entry.server.web.tsx integration/helpers/vite-plugin-cloudflare-template/app/entry.server.tsx renamed to packages/react-router-dev/config/defaults/entry.server.web.tsx

@@ -3,22 +3,33 @@ import { ServerRouter } from "react-router";
 import { isbot } from "isbot";
 import { renderToReadableStream } from "react-dom/server";
 
+export const streamTimeout = 5_000;
+
 export default async function handleRequest(
   request: Request,
   responseStatusCode: number,
   responseHeaders: Headers,
   routerContext: EntryContext,
   _loadContext: RouterContextProvider,
 ) {
+  // https://httpwg.org/specs/rfc9110.html#HEAD
+  if (request.method.toUpperCase() === "HEAD") {
+    return new Response(null, {
+      status: responseStatusCode,
+      headers: responseHeaders,
+    });
+  }
+
   let shellRendered = false;
-  const userAgent = request.headers.get("user-agent");
+  let userAgent = request.headers.get("user-agent");
 
   const body = await renderToReadableStream(
     <ServerRouter context={routerContext} url={request.url} />,
     {
+      signal: AbortSignal.timeout(streamTimeout + 1000),
       onError(error: unknown) {
         responseStatusCode = 500;
-        // Log streaming rendering errors from inside the shell.  Don't log
+        // 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) {

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

@@ -84,6 +84,7 @@ import {
   type BuildManifest,
   type ConfigLoader,
   createConfigLoader,
+  hasNodeDependency,
   resolveEntryFiles,
   configRouteToBranchRoute,
   type PrerenderPaths,
@@ -3577,11 +3578,7 @@ export async function getEnvironmentOptionsResolvers(
     let defaultExternalConditions = vite.defaultExternalConditions ?? ["node"];
 
     // If we couldn't find the package.json, we assume node for backwards compatibility
-    let isNode =
-      !pkgJson.dependencies ||
-      pkgJson.dependencies["@react-router/node"] ||
-      pkgJson.dependencies["@react-router/express"] ||
-      pkgJson.dependencies["@react-router/serve"];
+    let isNode = hasNodeDependency(pkgJson.dependencies);
 
     if (!isNode) {
       maybeDefaultServerConditions = maybeDefaultServerConditions.filter(