fix: load ESM-only dependencies with native import() in the CommonJS build (#5701)

* fix: load ESM-only dependencies with native import() in the CommonJS build

* fix: update dynamic import handling to ensure relative imports are converted to require() while preserving ESM-only imports

Author: bjohansebas

babel.config.js

@@ -1,28 +1,31 @@
+import rewriteRelativeDynamicImport from "./scripts/babel-plugin-rewrite-relative-dynamic-import.mjs";
+
 export default (api) => {
   // `api.env()` makes the resolved config cache depend on `BABEL_ENV`/`NODE_ENV`
   // so the `cjs` build and the default client build don't share a cache entry.
   const env = api.env();
 
-  // CommonJS build (`build:cjs`, `babel --env-name cjs`). `lib/` is authored as
-  // native ESM; here we transpile it to CJS for the dual package. `preset-env`
-  // with `modules: "commonjs"` rewrites `import()` into real `require()` (the
-  // target environments don't reliably support `require(ESM)`), and
-  // `babel-plugin-transform-import-meta` rewrites `import.meta.url` (used by
-  // `createRequire`) for CJS.
+  // CommonJS build. Transpile static `import`/`export` to CJS, but leave dynamic
+  // `import()` native (`exclude` below) so ESM-only deps load without
+  // `require(ESM)`; `rewrite-relative-dynamic-import` handles internal modules.
   if (env === "cjs") {
     return {
       presets: [
         [
           "@babel/preset-env",
           {
             modules: "commonjs",
+            exclude: ["@babel/plugin-transform-dynamic-import"],
             targets: {
               node: "22.15.0",
             },
           },
         ],
       ],
-      plugins: ["babel-plugin-transform-import-meta"],
+      plugins: [
+        "babel-plugin-transform-import-meta",
+        rewriteRelativeDynamicImport,
+      ],
     };
   }
 
@@ -40,20 +43,5 @@ export default (api) => {
       ],
     ],
     plugins: ["@babel/plugin-transform-object-assign"],
-    env: {
-      test: {
-        presets: [
-          [
-            "@babel/preset-env",
-            {
-              targets: {
-                node: "22.15.0",
-              },
-            },
-          ],
-        ],
-        plugins: ["@babel/plugin-transform-runtime"],
-      },
-    },
   };
 };

package-lock.json

@@ -89,9 +89,7 @@
     "@babel/core": "^7.29.0",
     "@babel/eslint-parser": "^7.28.6",
     "@babel/plugin-transform-object-assign": "^7.27.1",
-    "@babel/plugin-transform-runtime": "^7.29.0",
     "@babel/preset-env": "^7.29.2",
-    "@babel/runtime": "^7.29.2",
     "@changesets/cli": "^2.30.0",
     "@changesets/get-github-info": "^0.8.0",
     "@commitlint/cli": "^19.5.0",

package.json

@@ -0,0 +1,40 @@
+// Babel plugin (CJS build): rewrite only *relative* dynamic `import()` to
+// `require()` so babel's `.default` interop keeps working for our internal
+// modules. Bare/`node:` specifiers stay native `import()`, letting ESM-only
+// deps load without `require(ESM)`.
+export default ({ types: t }) => ({
+  name: "rewrite-relative-dynamic-import",
+  visitor: {
+    CallExpression(path) {
+      if (path.node.callee.type !== "Import") return;
+
+      const [arg] = path.node.arguments;
+
+      // a string-literal relative specifier (`./` or `../`) = an internal module
+      if (t.isStringLiteral(arg) && /^\.\.?\//.test(arg.value)) {
+        // `Promise.resolve().then(() => require(x))`: require runs in the
+        // callback so a load failure rejects (like `import()`), not throws.
+        path.replaceWith(
+          t.callExpression(
+            t.memberExpression(
+              t.callExpression(
+                t.memberExpression(
+                  t.identifier("Promise"),
+                  t.identifier("resolve"),
+                ),
+                [],
+              ),
+              t.identifier("then"),
+            ),
+            [
+              t.arrowFunctionExpression(
+                [],
+                t.callExpression(t.identifier("require"), [arg]),
+              ),
+            ],
+          ),
+        );
+      }
+    },
+  },
+});

scripts/babel-plugin-rewrite-relative-dynamic-import.mjs

@@ -114,14 +114,15 @@ describe("cjs", () => {
     expect(serverSource).toMatch(/exports\.default = /);
     expect(serverSource).toMatch(/module\.exports = exports\.default;/);
 
-    // No executable dynamic `import()` or `import.meta` survives in the CJS
-    // build. Strip comments first since JSDoc type annotations legitimately
-    // reference `import("pkg")` and `[S=import("http").Server]`.
+    // Relative `import("./…")` becomes `require()` and `import.meta` is gone,
+    // but bare `import("pkg")` stays native for ESM-only deps. Strip comments
+    // first (JSDoc legitimately references `import("pkg")`).
     const executableCode = serverSource
       .replaceAll(/\/\*[\s\S]*?\*\//g, "")
       .replaceAll(/^\s*\/\/.*$/gm, "");
 
-    expect(executableCode).not.toMatch(/import\(/);
+    expect(executableCode).not.toMatch(/import\(\s*["']\.\.?\//); // no relative
+    expect(executableCode).toMatch(/import\(\s*["']p-retry["']\)/); // bare stays
     expect(executableCode).not.toMatch(/import\.meta/);
   });