feat(dev): support empty server polyfills (#6859)

Co-authored-by: Matt Brophy <matt@brophy.org>
remix-run · Jul 18, 2023 · 472c936 · 472c936
1 parent fb875de
commit 472c936
Show file tree

Hide file tree

Showing 7 changed files with 58 additions and 21 deletions.
diff --git a/.changeset/nice-moons-kick.md b/.changeset/nice-moons-kick.md
@@ -0,0 +1,5 @@
+---
+"@remix-run/dev": minor
+---
+
+[REMOVE] Change serverNodeBuiltinsPolyfill to suport object format
diff --git a/.changeset/server-node-builtins-polyfill.md b/.changeset/server-node-builtins-polyfill.md
@@ -2,4 +2,17 @@
 "@remix-run/dev": minor
 ---
 
-Add `serverNodeBuiltinsPolyfill` config option. You can now disable polyfills of Node.js built-in modules for non-Node.js server platforms by setting `serverNodeBuiltinsPolyfill: false` in `remix.config.js`. You can also provide a list of server polyfills, e.g. `serverNodeBuiltinsPolyfill: ["crypto"]`.
+Add `serverNodeBuiltinsPolyfill` config option. In `remix.config.js` you can now disable polyfills of Node.js built-in modules for non-Node.js server platforms, or opt into a subset of polyfills.
+
+```js
+// Disable all polyfills
+exports.serverNodeBuiltinsPolyfill = false;
+
+// Enable specific polyfills
+exports.serverNodeBuiltinsPolyfill = {
+  modules: {
+    crypto: true, // Provide a JSPM polyfill
+    fs: 'empty', // Provide an empty polyfill
+  },
+};
+```
diff --git a/docs/file-conventions/remix-config.md b/docs/file-conventions/remix-config.md
@@ -193,14 +193,19 @@ Defaults to `"cjs"`.
 
 ## serverNodeBuiltinsPolyfill
 
-Whether to polyfill Node.js built-in modules in the server build, or a list of polyfills. Defaults to `true` for non-Node.js server platforms.
+Whether to polyfill Node.js built-in modules in the server build, or a configurable subset of polyfills. Polyfills are provided by [JSPM][jspm] and configured via [esbuild-plugins-node-modules-polyfill]. Defaults to `true` for non-Node.js server platforms.
 
 ```js filename=remix.config.js
-// disable all polyfills
+// Disable all polyfills
 exports.serverNodeBuiltinsPolyfill = false;
 
-// enable specific polyfills
-exports.serverNodeBuiltinsPolyfill = ["crypto"];
+// Enable specific polyfills
+exports.serverNodeBuiltinsPolyfill = {
+  modules: {
+    crypto: true, // Provide a JSPM polyfill
+    fs: 'empty', // Provide an empty polyfill
+  },
+};
 ```
 
 ## serverPlatform
@@ -254,3 +259,5 @@ There are a few conventions that Remix uses you should be aware of.
 [css-side-effect-imports]: ../guides/styling#css-side-effect-imports
 [postcss]: https://postcss.org
 [tailwind-functions-and-directives]: https://tailwindcss.com/docs/functions-and-directives
+[jspm]: https://github.com/jspm/jspm-core
+[esbuild-plugins-node-modules-polyfill]: https://www.npmjs.com/package/esbuild-plugins-node-modules-polyfill
diff --git a/packages/remix-dev/compiler/server/compiler.ts b/packages/remix-dev/compiler/server/compiler.ts
@@ -1,6 +1,9 @@
 import { builtinModules } from "module";
 import * as esbuild from "esbuild";
-import { nodeModulesPolyfillPlugin } from "esbuild-plugins-node-modules-polyfill";
+import {
+  type NodePolyfillsOptions,
+  nodeModulesPolyfillPlugin,
+} from "esbuild-plugins-node-modules-polyfill";
 
 import { type Manifest } from "../../manifest";
 import { loaders } from "../utils/loaders";
@@ -92,13 +95,19 @@ const createEsbuildConfig = (
       "v8", // https://github.com/jspm/jspm-core/blob/main/nodelibs/browser/v8.js
     ];
 
+    let defaultPolyfillOptions: NodePolyfillsOptions = {
+      modules: builtinModules.filter((mod) => !unimplemented.includes(mod)),
+    };
+
     plugins.unshift(
-      nodeModulesPolyfillPlugin({
-        modules:
-          ctx.config.serverNodeBuiltinsPolyfill === true
-            ? builtinModules.filter((mod) => !unimplemented.includes(mod))
-            : ctx.config.serverNodeBuiltinsPolyfill,
-      })
+      nodeModulesPolyfillPlugin(
+        ctx.config.serverNodeBuiltinsPolyfill === true
+          ? defaultPolyfillOptions
+          : {
+              // Ensure only "modules" option is passed to the plugin
+              modules: ctx.config.serverNodeBuiltinsPolyfill.modules,
+            }
+      )
     );
   }
 

diff --git a/packages/remix-dev/config.ts b/packages/remix-dev/config.ts
@@ -5,6 +5,7 @@ import fse from "fs-extra";
 import getPort from "get-port";
 import NPMCliPackageJson from "@npmcli/package-json";
 import { coerce } from "semver";
+import type { NodePolyfillsOptions } from "esbuild-plugins-node-modules-polyfill";
 
 import type { RouteManifest, DefineRoutesFunction } from "./config/routes";
 import { defineRoutes } from "./config/routes";
@@ -196,9 +197,10 @@ export interface AppConfig {
 
   /**
    * Whether to polyfill Node.js built-in modules in the server build, or a
-   * list of polyfills. Defaults to `true` for non-Node.js server platforms.
+   * configurable subset of polyfills. Defaults to `true` for non-Node.js server
+   * platforms.
    */
-  serverNodeBuiltinsPolyfill?: boolean | string[];
+  serverNodeBuiltinsPolyfill?: boolean | Pick<NodePolyfillsOptions, "modules">;
 
   /**
    * The platform the server build is targeting. Defaults to "node".
@@ -373,9 +375,10 @@ export interface RemixConfig {
 
   /**
    * Whether to polyfill Node.js built-in modules in the server build, or a
-   * list of polyfills. Defaults to `true` for non-Node.js server platforms.
+   * configurable subset of polyfills. Defaults to `true` for non-Node.js server
+   * platforms.
    */
-  serverNodeBuiltinsPolyfill: boolean | string[];
+  serverNodeBuiltinsPolyfill: boolean | Pick<NodePolyfillsOptions, "modules">;
 
   /**
    * The platform the server build is targeting. Defaults to "node".

diff --git a/packages/remix-dev/package.json b/packages/remix-dev/package.json
@@ -36,7 +36,7 @@
     "chokidar": "^3.5.1",
     "dotenv": "^16.0.0",
     "esbuild": "0.17.6",
-    "esbuild-plugins-node-modules-polyfill": "^1.2.0",
+    "esbuild-plugins-node-modules-polyfill": "^1.3.0",
     "execa": "5.1.1",
     "exit-hook": "2.2.1",
     "express": "^4.17.1",

diff --git a/yarn.lock b/yarn.lock
@@ -6132,10 +6132,10 @@ esbuild-openbsd-64@0.14.47:
   resolved "https://registry.npmjs.org/esbuild-openbsd-64/-/esbuild-openbsd-64-0.14.47.tgz#309af806db561aa886c445344d1aacab850dbdc5"
   integrity sha512-QpgN8ofL7B9z8g5zZqJE+eFvD1LehRlxr25PBkjyyasakm4599iroUpaj96rdqRlO2ShuyqwJdr+oNqWwTUmQw==
 
-esbuild-plugins-node-modules-polyfill@^1.2.0:
-  version "1.2.0"
-  resolved "https://registry.npmjs.org/esbuild-plugins-node-modules-polyfill/-/esbuild-plugins-node-modules-polyfill-1.2.0.tgz#06de57620bc470e78999ba99664dca936cfbe7c4"
-  integrity sha512-jWyCoWQKRbxUUfWLO900IyBDHihavTMbQLCDRq8xqj6NhQ75eW7YRvdraSDzFqQ6/eLnhNZlvantQtYbZjqU0A==
+esbuild-plugins-node-modules-polyfill@^1.3.0:
+  version "1.3.0"
+  resolved "https://registry.npmjs.org/esbuild-plugins-node-modules-polyfill/-/esbuild-plugins-node-modules-polyfill-1.3.0.tgz#aa61ca6189d54b163acc503b9fcbbbc825f28226"
+  integrity sha512-r/aNOvAlIaIzqJwvFHWhDGrPF/Aj5qI1zKVeHbCFpKH+bnKW1BG2LGixMd3s6hyWcZHcfdl2QZRucVuOLzFRrA==
   dependencies:
     "@jspm/core" "^2.0.1"
     local-pkg "^0.4.3"