docs: add docs for serverNodeBuiltinsPolyfill

chore: add warning
- rename config option
- update tests

docs/file-conventions/remix-config.md

@@ -191,10 +191,9 @@ Whether to minify the server build in production or not. Defaults to `false`.
 The output format of the server build, which can either be `"cjs"` or `"esm"`.
 Defaults to `"cjs"`.
 
-## serverNodeModulesPolyfill
+## serverNodeBuiltinsPolyfill
 
-Whether to polyfill Node.js built-in modules in the server build. Defaults to true
-for non-node server platforms.
+Whether to polyfill Node.js built-in modules in the server build. Defaults to true for non-node server platforms.
 
 ## serverPlatform
 

docs/pages/v2.md

@@ -703,6 +703,12 @@ The default server module output format will be changing from `cjs` to `esm`.
 
 In your `remix.config.js`, you should specify either `serverModuleFormat: "cjs"` to retain existing behavior, or `serverModuleFormat: "esm"`, to opt into the future behavior.
 
+## `serverNodeBuiltinsPolyfill`
+
+We will no longer polyfill node builtins by default on non-node server targets.
+
+If you are targeting a non-node platform for your server build, in your `remix.config.js`, you should specify either `serverNodeBuiltinsPolyfill: true` to retain existing behavior, or `serverNodeBuiltinsPolyfill: false`, to opt into the future default behavior.
+
 ## Dev Server
 
 We are still stabilizing the new dev server that enables HMR and simplifies integration with various servers. You can try it today with `unstable_dev` and referring to the [v1.16 Release Notes][v1-16-release-notes] to set it up.

packages/remix-dev/__tests__/readConfig-test.ts

@@ -86,6 +86,7 @@ describe("readConfig", () => {
         "serverMinify": false,
         "serverMode": "production",
         "serverModuleFormat": "cjs",
+        "serverNodeBuiltinsPolyfill": false,
         "serverPlatform": "node",
         "tailwind": false,
         "tsconfigPath": Any<String>,

packages/remix-dev/compiler/server/compiler.ts

@@ -60,7 +60,7 @@ const createEsbuildConfig = (
     externalPlugin(/^node:.*/, { sideEffects: false }),
   ];
 
-  if (ctx.config.serverNodeModulesPolyfill) {
+  if (ctx.config.serverNodeBuiltinsPolyfill) {
     plugins.unshift(nodeModulesPolyfillPlugin());
   }
 

packages/remix-dev/config.ts

@@ -192,7 +192,7 @@ export interface AppConfig {
   /**
    * Whether to polyfill Node.js built-in modules in the server build.
    */
-  serverNodeModulesPolyfill?: boolean;
+  serverNodeBuiltinsPolyfill?: boolean;
 
   /**
    * The platform the server build is targeting. Defaults to "node".
@@ -368,7 +368,7 @@ export interface RemixConfig {
   /**
    * Whether to polyfill Node.js built-in modules in the server build.
    */
-  serverNodeModulesPolyfill: boolean;
+  serverNodeBuiltinsPolyfill: boolean;
 
   /**
    * The platform the server build is targeting. Defaults to "node".
@@ -496,9 +496,16 @@ export async function readConfig(
     serverModuleFormat === "esm" ? ["module", "main"] : ["main", "module"];
   serverMinify ??= false;
 
-  let serverNodeModulesPolyfill = serverPlatform !== "node";
-  if (typeof appConfig.serverNodeModulesPolyfill === "boolean") {
-    serverNodeModulesPolyfill = appConfig.serverNodeModulesPolyfill;
+  let serverNodeBuiltinsPolyfill = serverPlatform !== "node";
+  if (typeof appConfig.serverNodeBuiltinsPolyfill === "boolean") {
+    serverNodeBuiltinsPolyfill = appConfig.serverNodeBuiltinsPolyfill;
+  }
+
+  if (
+    serverPlatform !== "node" &&
+    typeof appConfig.serverNodeBuiltinsPolyfill !== "boolean"
+  ) {
+    warnOnce(serverNodeBuiltinsPolyfillWarning, "serverNodeBuiltinsPolyfill");
   }
 
   if (appConfig.future) {
@@ -786,7 +793,7 @@ export async function readConfig(
     serverMinify,
     serverMode,
     serverModuleFormat,
-    serverNodeModulesPolyfill,
+    serverNodeBuiltinsPolyfill,
     serverPlatform,
     mdx,
     postcss,
@@ -924,6 +931,13 @@ export const serverModuleFormatWarning =
   "For instructions on making this change see " +
   "https://remix.run/docs/en/v1.16.0/pages/v2#servermoduleformat";
 
+export const serverNodeBuiltinsPolyfillWarning =
+  "⚠️ REMIX FUTURE CHANGE: The `serverNodeBuiltinsPolyfill` config default option will be changing in v2 " +
+  "from `true` to `false` regardless of platform. You can prepare for this change by explicitly specifying " +
+  "serverNodeBuiltinsPolyfill: false` or `serverNodeBuiltinsPolyfill: true` if you are currently relying on them. " +
+  "For instructions on making this change see " +
+  "https://remix.run/docs/en/v1.16.0/pages/v2#servernodebuiltinspolyfill";
+
 export let flatRoutesWarning =
   "⚠️ REMIX FUTURE CHANGE: The route file convention is changing in v2. " +
   "You can prepare for this change at your convenience with the `v2_routeConvention` future flag. " +