From 45be6af0c4ca788f71c68fab4093bd0274ba8565 Mon Sep 17 00:00:00 2001 From: RoomWithOutRoof Date: Wed, 15 Apr 2026 06:51:38 +0800 Subject: [PATCH] doc: add guidance on using node/default conditions for dual packages As an alternative to using "import"/"require" conditions, packages can use "node"/"default" conditions to avoid the dual package hazard while still providing ES modules for non-Node.js environments. This addresses issue #52174. --- doc/api/packages.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/doc/api/packages.md b/doc/api/packages.md index 429b1b19b90801..42e22f124eb02b 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -720,6 +720,24 @@ least specific in object order_. Using the `"import"` and `"require"` conditions can lead to some hazards, which are further explained in [the dual CommonJS/ES module packages section][]. +As an alternative to using `"import"` and `"require"`, packages can use +`"node"` and `"default"` conditions to avoid the dual package hazard while +still providing ES modules for non-Node.js environments. + +For example, using `"node"` and `"default"` instead of `"require"` and `"import"`: + +```json +{ + "exports": { + "node": "./index.cjs", + "default": "./index.mjs" + } +} +``` + +This approach avoids the dual package hazard in Node.js (since `"node"` always +matches for any Node.js environment) while still allowing bundlers to use the +ES module version when targeting other JavaScript runtimes. The `"node-addons"` condition can be used to provide an entry point which uses native C++ addons. However, this condition can be disabled via the