Add more detailed suggestion when importing Node built-in modules

Author: mrbbot

packages/runner-vm/src/linker.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from "fs";
 import fs from "fs/promises";
+import { builtinModules } from "module";
 import path from "path";
 import vm from "vm";
 import {
@@ -14,6 +15,13 @@ import { VMScriptRunnerError } from "./error";
 const SUGGEST_BUNDLE =
   "If you're trying to import an npm package, you'll need to bundle your Worker first.";
 
+const SUGGEST_NODE =
+  "If you're trying to import a Node.js built-in module, or an npm package " +
+  "that uses Node.js built-ins, you'll either need to:" +
+  "\n- Bundle your Worker, configuring your bundler to polyfill Node.js built-ins" +
+  "\n- Configure your bundler to load Workers-compatible builds by changing the main fields/conditions" +
+  "\n- Find an alternative package that doesn't require Node.js built-ins";
+
 interface CommonJSModule {
   exports: any;
 }
@@ -87,9 +95,11 @@ export class ModuleLinker {
       rule.include.test(relativeIdentifier)
     );
     if (rule === undefined) {
+      const isBuiltin = builtinModules.includes(spec);
+      const suggestion = isBuiltin ? SUGGEST_NODE : SUGGEST_BUNDLE;
       throw new VMScriptRunnerError(
         "ERR_MODULE_RULE",
-        `${errorBase}: no matching module rules.\n${SUGGEST_BUNDLE}`
+        `${errorBase}: no matching module rules.\n${suggestion}`
       );
     }
 
@@ -179,9 +189,11 @@ export class ModuleLinker {
       rule.include.test(relativeIdentifier)
     );
     if (rule === undefined) {
+      const isBuiltin = builtinModules.includes(spec);
+      const suggestion = isBuiltin ? SUGGEST_NODE : SUGGEST_BUNDLE;
       throw new VMScriptRunnerError(
         "ERR_MODULE_RULE",
-        `${errorBase}: no matching module rules.\n${SUGGEST_BUNDLE}`
+        `${errorBase}: no matching module rules.\n${suggestion}`
       );
     }
 

packages/runner-vm/test/fixtures/cjsbuiltin.cjs

@@ -0,0 +1 @@
+module.exports = require("path");

packages/runner-vm/test/linker.spec.ts

@@ -110,7 +110,16 @@ test("ModuleLinker: throws error if no matching module rule via ES module", asyn
   await t.throwsAsync(result, {
     instanceOf: VMScriptRunnerError,
     code: "ERR_MODULE_RULE",
-    message: /no matching module rules/,
+    message: /no matching module rules.*\nIf you're trying to import an npm/,
+  });
+});
+test("ModuleLinker: throws error for Node built-in module via ES module", async (t) => {
+  const result = run(`import fs from "fs"`);
+  await t.throwsAsync(result, {
+    instanceOf: VMScriptRunnerError,
+    code: "ERR_MODULE_RULE",
+    message:
+      /no matching module rules.*\nIf you're trying to import a Node\.js built-in/,
   });
 });
 test("ModuleLinker: throws error for unsupported module type via ES module", async (t) => {
@@ -181,7 +190,18 @@ test("ModuleLinker: throws error if no matching module rule via CommonJS module"
   await t.throwsAsync(result, {
     instanceOf: VMScriptRunnerError,
     code: "ERR_MODULE_RULE",
-    message: /no matching module rules/,
+    message: /no matching module rules.*\nIf you're trying to import an npm/,
+  });
+});
+test("ModuleLinker: throws error for Node built-in module via CommonJS module", async (t) => {
+  const result = run(
+    `import value from "./cjsbuiltin.cjs"; export default value;`
+  );
+  await t.throwsAsync(result, {
+    instanceOf: VMScriptRunnerError,
+    code: "ERR_MODULE_RULE",
+    message:
+      /no matching module rules.*\nIf you're trying to import a Node\.js built-in/,
   });
 });
 test("ModuleLinker: throws error for unsupported module type via CommonJS module", async (t) => {