feat: add nodeProtocol option (#336)

ryoppippi · sxzz · web-flow · commit b3f671a5b329 · 2025-06-22T11:54:36.000+08:00
Co-authored-by: 三咲智子 Kevin Deng &lt;sxzz@sxzz.moe&gt;
diff --git a/docs/guide/migrate-from-tsup.md b/docs/guide/migrate-from-tsup.md
@@ -37,6 +37,15 @@ While `tsdown` aims to be highly compatible with `tsup`, there are some differen
 
 Some features available in `tsup` are not yet implemented in `tsdown`. If you find an option missing that you need, please [open an issue](https://github.com/rolldown/tsdown/issues) to let us know your requirements.
 
+### New Features in tsdown
+
+`tsdown` also introduces new features not available in `tsup`:
+
+- **`nodeProtocol`**: Control how Node.js built-in module imports are handled:
+  - `true`: Add `node:` prefix to built-in modules (e.g., `fs` → `node:fs`)
+  - `'strip'`: Remove `node:` prefix from imports (e.g., `node:fs` → `fs`)
+  - `false`: Keep imports as-is (default)
+
 Please review your configuration after migration to ensure it matches your expectations.
 
 ## Acknowledgements
diff --git a/docs/reference/config-options.md b/docs/reference/config-options.md
@@ -447,13 +447,15 @@ false
 
 ***
 
-### removeNodeProtocol?
+### nodeProtocol?
 
-> `optional` **removeNodeProtocol**: `boolean`
+> `optional` **nodeProtocol**: `'strip'` \| `boolean`
 
-Defined in: [types.ts:319](https://github.com/rolldown/tsdown/blob/0978c68bd505c76d7e3097572cd652f81c23f97e/src/options/types.ts#L319)
+Defined in: [types.ts:336](https://github.com/rolldown/tsdown/blob/0978c68bd505c76d7e3097572cd652f81c23f97e/src/options/types.ts#L336)
 
-If enabled, strips the `node:` protocol prefix from import source.
+- If true, add `node:` prefix to built-in modules.
+- If 'strip', strips the `node:` protocol prefix from import source.
+- If false, does not modify the import source.
 
 #### Default
 
@@ -463,9 +465,15 @@ false
 
 #### Example
 
+<!-- eslint-skip -->
+
 ```ts
-// With removeNodeProtocol enabled:
+// With nodeProtocol enabled:
+import('fs'); // becomes import('node:fs')
+// With nodeProtocol set to 'strip':
 import('node:fs'); // becomes import('fs')
+// With nodeProtocol set to false:
+import('node:fs'); // remains import('node:fs')
 ```
 
 ***
diff --git a/docs/zh-CN/guide/migrate-from-tsup.md b/docs/zh-CN/guide/migrate-from-tsup.md
@@ -37,6 +37,15 @@ npx tsdown migrate
 
 `tsdown` 尚未实现 `tsup` 中的某些功能。如果您发现缺少某些您需要的选项，请 [提交问题](https://github.com/rolldown/tsdown/issues) 告诉我们您的需求。
 
+### tsdown 的新功能
+
+`tsdown` 还引入了一些 `tsup` 中没有的新功能：
+
+- **`nodeProtocol`**：控制 Node.js 内置模块导入的处理方式：
+  - `true`：为内置模块添加 `node:` 前缀（例如，`fs` → `node:fs`）
+  - `'strip'`：从导入中移除 `node:` 前缀（例如，`node:fs` → `fs`）
+  - `false`：保持导入不变（默认）
+
 迁移后，请仔细检查您的配置以确保其符合您的预期。
 
 ## 致谢
diff --git a/docs/zh-CN/reference/config-options.md b/docs/zh-CN/reference/config-options.md
@@ -447,28 +447,6 @@ false
 
 ***
 
-### removeNodeProtocol?
-
-> `optional` **removeNodeProtocol**: `boolean`
-
-Defined in: [types.ts:319](https://github.com/rolldown/tsdown/blob/0978c68bd505c76d7e3097572cd652f81c23f97e/src/options/types.ts#L319)
-
-If enabled, strips the `node:` protocol prefix from import source.
-
-#### Default
-
-```ts
-false
-```
-
-#### Example
-
-```ts
-// With removeNodeProtocol enabled:
-import('node:fs'); // becomes import('fs')
-```
-
-***
 
 ### report?
 
diff --git a/src/features/node-protocol.ts b/src/features/node-protocol.ts
@@ -1,18 +1,40 @@
+import { builtinModules } from 'node:module'
 import type { Plugin } from 'rolldown'
 
 /**
  * The `node:` protocol was added in Node.js v14.18.0.
  * @see https://nodejs.org/api/esm.html#node-imports
  */
-export function NodeProtocolPlugin(): Plugin {
+export function NodeProtocolPlugin(nodeProtocolOption: 'strip' | true): Plugin {
+  if (nodeProtocolOption === 'strip') {
+    return {
+      name: 'tsdown:node-protocol:strip',
+      resolveId: {
+        order: 'pre',
+        filter: { id: /^node:/ },
+        handler(id) {
+          return {
+            id: id.slice(5), // strip the `node:` prefix
+            external: true,
+            moduleSideEffects: false,
+          }
+        },
+      },
+    }
+  }
+
+  // create regex from builtin modules
+  // filter without `node:` prefix
+  const builtinModulesRegex = new RegExp(`^(${builtinModules.join('|')})$`)
+
   return {
-    name: 'tsdown:node-protocol',
+    name: 'tsdown:node-protocol:add',
     resolveId: {
       order: 'pre',
-      filter: { id: /^node:/ },
+      filter: { id: builtinModulesRegex },
       handler(id) {
         return {
-          id: id.slice(5),
+          id: `node:${id}`,
           external: true,
           moduleSideEffects: false,
         }
diff --git a/src/index.ts b/src/index.ts
@@ -210,16 +210,16 @@ async function getBuildOptions(
     cwd,
     report,
     env,
-    removeNodeProtocol,
+    nodeProtocol,
     loader,
     name,
     unbundle,
   } = config
 
   const plugins: RolldownPluginOption = []
 
-  if (removeNodeProtocol) {
-    plugins.push(NodeProtocolPlugin())
+  if (nodeProtocol) {
+    plugins.push(NodeProtocolPlugin(nodeProtocol))
   }
 
   if (config.pkg || config.skipNodeModulesBundle) {
diff --git a/src/options/index.ts b/src/options/index.ts
@@ -208,12 +208,21 @@ async function resolveConfig(
     exports = false,
     bundle,
     unbundle = typeof bundle === 'boolean' ? !bundle : false,
+    removeNodeProtocol,
+    nodeProtocol,
   } = userConfig
 
   if (typeof bundle === 'boolean') {
     logger.warn('`bundle` option is deprecated. Use `unbundle` instead.')
   }
 
+  // Resolve nodeProtocol option with backward compatibility for removeNodeProtocol
+  nodeProtocol =
+    nodeProtocol ??
+    // `removeNodeProtocol: true` means stripping the `node:` protocol which equals to `nodeProtocol: 'strip'`
+    // `removeNodeProtocol: false` means keeping the `node:` protocol which equals to `nodeProtocol: false` (ignore it)
+    (removeNodeProtocol ? 'strip' : false)
+
   outDir = path.resolve(cwd, outDir)
   clean = resolveClean(clean, outDir, cwd)
 
@@ -310,6 +319,7 @@ async function resolveConfig(
     noExternal,
     exports,
     unbundle,
+    nodeProtocol,
   }
 
   return config
diff --git a/src/options/types.ts b/src/options/types.ts
@@ -311,13 +311,32 @@ export interface Options {
    * If enabled, strips the `node:` protocol prefix from import source.
    *
    * @default false
+   * @deprecated Use `nodeProtocol: 'strip'` instead.
    *
    * @example
    * // With removeNodeProtocol enabled:
    * import('node:fs'); // becomes import('fs')
    */
   removeNodeProtocol?: boolean
 
+  /**
+   * - If true, add `node:` prefix to built-in modules.
+   * - If 'strip', strips the `node:` protocol prefix from import source.
+   * - If false, does not modify the import source.
+   *
+   * @default false
+   *
+   * @example
+   * // With nodeProtocol enabled:
+   * import('fs'); // becomes import('node:fs')
+   * // With nodeProtocol set to 'strip':
+   * import('node:fs'); // becomes import('fs')
+   * // With nodeProtocol set to false:
+   * import('node:fs'); // remains import('node:fs')
+   *
+   */
+  nodeProtocol?: 'strip' | boolean
+
   /**
    * If enabled, appends hash to chunk filenames.
    * @default true
@@ -380,6 +399,7 @@ export type ResolvedOptions = Omit<
       tsconfig: string | false
       pkg?: PackageJson
       exports: false | ExportsOptions
+      nodeProtocol: 'strip' | boolean
     }
   >,
   'config' | 'fromVite'
diff --git a/tests/__snapshots__/node-protocol/dynamic-imports-with-nodeProtocol-true.snap.md b/tests/__snapshots__/node-protocol/dynamic-imports-with-nodeProtocol-true.snap.md
@@ -0,0 +1,16 @@
+## index.js
+
+```js
+//#region index.ts
+async function loadBuiltins() {
+	const fs = await import("node:fs");
+	const path = await import("node:path");
+	return {
+		fs,
+		path
+	};
+}
+
+//#endregion
+export { loadBuiltins };
+```
diff --git a/tests/__snapshots__/node-protocol/mixed-imports-with-nodeProtocol-true.snap.md b/tests/__snapshots__/node-protocol/mixed-imports-with-nodeProtocol-true.snap.md
@@ -0,0 +1,9 @@
+## index.js
+
+```js
+import fs from "node:fs";
+import { join } from "node:path";
+import express from "express";
+
+export { express, fs, join };
+```
diff --git a/tests/__snapshots__/node-protocol/nodeProtocol-default-false-.snap.md b/tests/__snapshots__/node-protocol/nodeProtocol-default-false-.snap.md
@@ -0,0 +1,8 @@
+## index.js
+
+```js
+import fs from "node:fs";
+import path from "path";
+
+export { fs, path };
+```
diff --git a/tests/__snapshots__/node-protocol/nodeProtocol-false-no-modification-.snap.md b/tests/__snapshots__/node-protocol/nodeProtocol-false-no-modification-.snap.md
@@ -0,0 +1,12 @@
+## index.js
+
+```js
+import fs from "node:fs";
+import path from "path";
+
+//#region index.ts
+const promise = import("node:fs/promises");
+
+//#endregion
+export { fs, path, promise };
+```
diff --git a/tests/__snapshots__/node-protocol/nodeProtocol-option-takes-precedence-over-removeNodeProtocol.snap.md b/tests/__snapshots__/node-protocol/nodeProtocol-option-takes-precedence-over-removeNodeProtocol.snap.md
@@ -0,0 +1,7 @@
+## index.js
+
+```js
+import fs from "node:fs";
+
+export { fs };
+```
diff --git a/tests/__snapshots__/node-protocol/nodeProtocol-strip-same-as-removeNodeProtocol-true-.snap.md b/tests/__snapshots__/node-protocol/nodeProtocol-strip-same-as-removeNodeProtocol-true-.snap.md
@@ -0,0 +1,12 @@
+## index.js
+
+```js
+import fs from "fs";
+import { join } from "path";
+
+//#region index.ts
+const promise = import("fs/promises");
+
+//#endregion
+export { fs, join, promise };
+```
diff --git a/tests/__snapshots__/node-protocol/nodeProtocol-true-add-node-prefix-.snap.md b/tests/__snapshots__/node-protocol/nodeProtocol-true-add-node-prefix-.snap.md
@@ -0,0 +1,13 @@
+## index.js
+
+```js
+import fs from "node:fs";
+import { join } from "node:path";
+import * as crypto from "node:crypto";
+
+//#region index.ts
+const promise = import("node:fs/promises");
+
+//#endregion
+export { crypto, fs, join, promise };
+```
diff --git a/tests/__snapshots__/node-protocol/removeNodeProtocol-takes-precedence-when-nodeProtocol-is-not-set.snap.md b/tests/__snapshots__/node-protocol/removeNodeProtocol-takes-precedence-when-nodeProtocol-is-not-set.snap.md
@@ -0,0 +1,7 @@
+## index.js
+
+```js
+import fs from "fs";
+
+export { fs };
+```
diff --git a/tests/__snapshots__/node-protocol/subpath-imports-with-nodeProtocol-true.snap.md b/tests/__snapshots__/node-protocol/subpath-imports-with-nodeProtocol-true.snap.md
@@ -0,0 +1,8 @@
+## index.js
+
+```js
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+export { fileURLToPath, readFile };
+```
diff --git a/tests/__snapshots__/node-protocol/with-require-polyfill-and-nodeProtocol-strip.snap.md b/tests/__snapshots__/node-protocol/with-require-polyfill-and-nodeProtocol-strip.snap.md
@@ -0,0 +1,15 @@
+## index.js
+
+```js
+import { createRequire } from "module";
+
+//#region rolldown:runtime
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+//#endregion
+//#region index.ts
+const fn = __require.resolve;
+
+//#endregion
+export { fn };
+```
diff --git a/tests/node-protocol.test.ts b/tests/node-protocol.test.ts
