rolldown-plugin-require-cjs 0.1.5 → 0.3.0

package/README.md

@@ -10,14 +10,58 @@ Transform ESM imports to CJS requires when the imported module is pure CJS.
 
 Some packages only provide CJS builds (e.g., [`typescript`](https://npmjs.com/package/typescript), [`@babel/parser`](https://npmjs.com/package/@babel/parser)), and importing them using ESM syntax increases Node's `cjs-module-lexer` overhead. This plugin converts ESM imports to CJS requires for such pure CJS packages, allowing Node to skip the cjs-module-lexer step and improve performance.
 
+If performance is insignificant for your project, please do not use this plugin, as it introduces additional complexity and maintenance overhead.
+
 See more: https://x.com/sanxiaozhizi/status/1968580207322808812
 
+## Appeal
+
+We encourage the JavaScript ecosystem to continue its transition toward ESM. If you maintain a package that is still CJS-only, please consider offering an ESM build or migrating fully to ESM. Doing so will reduce reliance on plugins like this one and enhance the overall performance of the ecosystem.
+
 ## Install
 
 ```bash
 npm i rolldown-plugin-require-cjs
 ```
 
+## Options
+
+```ts
+export interface Options {
+  include?: Array<string | RegExp> | string | RegExp
+  exclude?: Array<string | RegExp> | string | RegExp
+  order?: 'pre' | 'post' | undefined
+  /**
+   * A function to determine whether a module should be transformed.
+   * Return `true` to force transformation, `false` to skip transformation,
+   * or `undefined` to let the plugin decide automatically.
+   */
+  shouldTransform?: string[] | TransformFn
+  /**
+   * Whether to transform Node.js built-in modules (e.g., `fs`, `path`)
+   * to `process.getBuiltinModule()` calls, which has the best performance.
+   *
+   * Note: `process.getBuiltinModule` is available since Node.js 20.16.0 and 22.3.0.
+   */
+  builtinNodeModules?: boolean
+}
+
+/**
+ * @returns A boolean or a promise that resolves to a boolean,
+ * or `undefined` to let the plugin decide automatically.
+ */
+export type TransformFn = (
+  /**
+   * The module ID (path) being imported.
+   */
+  id: string,
+  /**
+   * The module ID (path) of the importer.
+   */
+  importer: string,
+) => Awaitable<boolean | undefined | void>
+```
+
 ## Example
 
 ```ts

package/dist/index.d.ts

@@ -1,23 +1,31 @@
+import { FilterPattern } from "unplugin-utils";
 import { Plugin } from "rolldown";
 
 //#region src/options.d.ts
-type FilterPattern = Array<string | RegExp> | string | RegExp;
 type Awaitable<T> = T | Promise<T>;
+/**
+* @returns A boolean or a promise that resolves to a boolean,
+* or `undefined` to let the plugin decide automatically.
+*/
 type TransformFn = (id: string, importer: string) => Awaitable<boolean | undefined | void>;
 interface Options {
   include?: FilterPattern;
   exclude?: FilterPattern;
   order?: "pre" | "post" | undefined;
+  cwd?: string;
   /**
   * A function to determine whether a module should be transformed.
   * Return `true` to force transformation, `false` to skip transformation,
   * or `undefined` to let the plugin decide automatically.
-  *
-  * @param id The module ID (path) being imported.
-  * @param importer The module ID (path) of the importer.
-  * @returns A boolean or a promise that resolves to a boolean, or `undefined`.
   */
   shouldTransform?: string[] | TransformFn;
+  /**
+  * Whether to transform Node.js built-in modules (e.g., `fs`, `path`)
+  * to `process.getBuiltinModule()` calls, which has the best performance.
+  *
+  * Note: `process.getBuiltinModule` is available since Node.js 20.16.0 and 22.3.0.
+  */
+  builtinNodeModules?: boolean;
 }
 type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U;
 type OptionsResolved = Overwrite<Required<Options>, Pick<Options, "order"> & {

package/dist/index.js

@@ -1,4 +1,4 @@
-import { createRequire } from "node:module";
+import { builtinModules, createRequire } from "node:module";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { init, parse } from "cjs-module-lexer";
@@ -6,6 +6,8 @@ import { up } from "empathic/package";
 import { MagicStringAST, generateTransform } from "magic-string-ast";
 import { resolvePathSync } from "mlly";
 import { parseAst } from "rolldown/parseAst";
+import { createFilter } from "unplugin-utils";
+import process from "node:process";
 
 //#region rolldown:runtime
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
@@ -21,20 +23,26 @@ function resolveOptions(options) {
 		include: options.include || [/\.[cm]?[jt]sx?$/],
 		exclude: options.exclude || [/node_modules/, /\.d\.[cm]?ts$/],
 		order: "order" in options ? options.order : "pre",
-		shouldTransform: options.shouldTransform
+		cwd: options.cwd || process.cwd(),
+		shouldTransform: options.shouldTransform,
+		builtinNodeModules: !!options.builtinNodeModules
 	};
 }
 
 //#endregion
 //#region src/index.ts
 let initted = false;
+const REQUIRE = `__cjs_require`;
 function RequireCJS(userOptions = {}) {
-	const { include, exclude, order, shouldTransform } = resolveOptions(userOptions);
+	const { include, exclude, order, cwd, shouldTransform, builtinNodeModules } = resolveOptions(userOptions);
+	const filter = createFilter(include, exclude);
 	return {
 		name: "rolldown-plugin-require-cjs",
 		async buildStart() {
-			await init();
-			initted = true;
+			if (!initted) {
+				await init();
+				initted = true;
+			}
 		},
 		options(options) {
 			if (options.platform !== "node") this.error("`rolldown-plugin-require-cjs` plugin is designed only for the Node.js environment. Please make sure to set `platform: \"node\"` in the options.");
@@ -46,42 +54,56 @@ function RequireCJS(userOptions = {}) {
 				"module"
 			].includes(options.format)) throw new Error("`rolldown-plugin-require-cjs` plugin is only necessary for ESM output");
 		},
-		transform: {
-			filter: { id: {
-				include,
-				exclude
-			} },
+		renderChunk: {
 			order,
-			async handler(code, id) {
-				const { body } = parseAst(code, { lang: void 0 }, id);
+			async handler(code, { fileName }) {
+				if (!filter(fileName)) return;
+				const { body } = parseAst(code, { lang: void 0 }, fileName);
 				const s = new MagicStringAST(code);
+				let usingRequire = false;
 				for (const stmt of body) if (stmt.type === "ImportDeclaration") {
 					if (stmt.importKind === "type") continue;
 					const source = stmt.source.value;
-					const resolution = await this.resolve(source, id);
-					if (resolution && resolution.external === false) continue;
-					if (!(await shouldTransform?.(source, id) ?? await isPureCJS(source, id))) continue;
+					const isBuiltinModule = builtinNodeModules && (builtinModules.includes(source) || source.startsWith("node:"));
+					if (!(isBuiltinModule || (await shouldTransform?.(source, cwd) ?? await isPureCJS(source, cwd)))) continue;
 					if (stmt.specifiers.length === 0) {
-						s.overwriteNode(stmt, `require(${s.sliceNode(stmt.source)});`);
+						if (isBuiltinModule) s.removeNode(stmt);
+						else {
+							s.overwriteNode(stmt, `${REQUIRE}(${JSON.stringify(source)});`);
+							usingRequire = true;
+						}
 						continue;
 					}
-					const mapping = {};
+					const mapping = [];
 					let namespaceId;
 					let defaultId;
-					for (const specifier of stmt.specifiers) if (specifier.type === "ImportNamespaceSpecifier") namespaceId = s.sliceNode(specifier.local);
+					for (const specifier of stmt.specifiers) if (specifier.type === "ImportNamespaceSpecifier") namespaceId = specifier.local.name;
 					else if (specifier.type === "ImportSpecifier") {
 						if (specifier.importKind === "type") continue;
-						mapping[s.sliceNode(specifier.imported)] = s.sliceNode(specifier.local);
-					} else defaultId = s.sliceNode(specifier.local);
-					const requireCode = `require(${s.sliceNode(stmt.source)})`;
-					let str = "";
+						mapping.push([s.sliceNode(specifier.imported), specifier.local.name]);
+					} else defaultId = specifier.local.name;
+					let requireCode;
+					if (isBuiltinModule) requireCode = source === "process" || source === "node:process" ? "globalThis.process" : `globalThis.process.getBuiltinModule(${JSON.stringify(source)})`;
+					else {
+						requireCode = `__cjs_require(${JSON.stringify(source)})`;
+						usingRequire = true;
+					}
+					const codes = [];
 					if (namespaceId) defaultId ||= `_cjs_${namespaceId}_default`;
-					if (defaultId) str += `const ${defaultId} = ${requireCode};`;
-					if (namespaceId) str += `const ${namespaceId} = { ...${defaultId}, default: ${defaultId} };`;
-					if (Object.keys(mapping).length > 0) str += `const { ${Object.entries(mapping).map(([k, v]) => `${k}: ${v}`).join(", ")} } = ${defaultId || requireCode};`;
-					s.overwriteNode(stmt, str);
+					if (defaultId) codes.push(`const ${defaultId} = ${requireCode};`);
+					if (namespaceId) codes.push(`const ${namespaceId} = { ...${defaultId}, default: ${defaultId} };`);
+					if (mapping.length > 0) codes.push(`const {\n${mapping.map(([k, v]) => `  ${k === v ? v : `${k}: ${v}`}`).join(",\n")}\n} = ${defaultId || requireCode};`);
+					s.overwriteNode(stmt, codes.join("\n"));
+				}
+				if (usingRequire) {
+					const preamble = builtinNodeModules ? `const ${REQUIRE} = globalThis.process.getBuiltinModule("module").createRequire(import.meta.url);\n` : `import { createRequire as __cjs_createRequire } from "node:module";
+const ${REQUIRE} = __cjs_createRequire(import.meta.url);\n`;
+					if (code[0] === "#") {
+						const firstNewLineIndex = code.indexOf("\n") + 1;
+						s.appendLeft(firstNewLineIndex, preamble);
+					} else s.prepend(preamble);
 				}
-				return generateTransform(s, id);
+				return generateTransform(s, fileName);
 			}
 		}
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rolldown-plugin-require-cjs",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "description": "Transform ESM imports to CJS requires when the imported module is pure CJS.",
   "type": "module",
   "license": "MIT",
@@ -34,20 +34,21 @@
     "cjs-module-lexer": "^2.1.0",
     "empathic": "^2.0.0",
     "magic-string-ast": "^1.0.2",
-    "mlly": "^1.8.0"
+    "mlly": "^1.8.0",
+    "unplugin-utils": "^0.3.0"
   },
   "devDependencies": {
     "@babel/parser": "^7.28.4",
-    "@sxzz/eslint-config": "^7.1.4",
+    "@sxzz/eslint-config": "^7.2.5",
     "@sxzz/prettier-config": "^2.2.4",
     "@sxzz/test-utils": "^0.5.11",
-    "@types/node": "^24.4.0",
+    "@types/node": "^24.5.2",
     "bumpp": "^10.2.3",
-    "eslint": "^9.35.0",
+    "eslint": "^9.36.0",
     "eslint-plugin-vue": "^10.5.0",
     "prettier": "^3.6.2",
-    "rolldown": "1.0.0-beta.38",
-    "tsdown": "^0.15.1",
+    "rolldown": "1.0.0-beta.40",
+    "tsdown": "^0.15.4",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4"
   },