Skip to content

Commit e392a48

Browse files
committed
doc: add approach for using a single format with default
Address review feedback by adding Approach 1 that recommends using just the "default" condition with a single format as the simplest solution to the dual package hazard.
1 parent f9cc655 commit e392a48

File tree

1 file changed

+36
-5
lines changed

1 file changed

+36
-5
lines changed

doc/api/packages.md

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -967,11 +967,41 @@ If one dependency `require()`s `my-package` while another `import`s it, two
967967
separate copies of the package are loaded. Any state or objects exported by the
968968
package will not be shared between the two copies.
969969

970-
### Approach 1: Use `node` and `default` conditions
970+
### Approach 1: Use a single format with `default`
971971

972-
The recommended approach to avoid the dual package hazard while still providing
973-
both CommonJS and ES module entry points is to use the `"node"` and `"default"`
974-
conditions instead of `"require"` and `"import"`:
972+
The simplest way to avoid the dual package hazard is to pick one format and
973+
export it using the `"default"` condition:
974+
975+
```json
976+
{
977+
"name": "my-package",
978+
"exports": {
979+
"default": "./index.cjs"
980+
}
981+
}
982+
```
983+
984+
If the package uses CommonJS, non-Node.js environments will need to bundle it.
985+
Alternatively, an ES module entry point can be used:
986+
987+
```json
988+
{
989+
"name": "my-package",
990+
"exports": {
991+
"default": "./index.mjs"
992+
}
993+
}
994+
```
995+
996+
In this case, CommonJS consumers can only use the package in Node.js versions
997+
that support [`require()` of ES modules][]. ESM consumers can always `import`
998+
it regardless of the format.
999+
1000+
### Approach 2: Use `node` and `default` conditions
1001+
1002+
If the package needs to provide different entry points for Node.js and other
1003+
environments, use the `"node"` and `"default"` conditions instead of
1004+
`"require"` and `"import"`:
9751005

9761006
```json
9771007
{
@@ -995,7 +1025,7 @@ This approach ensures there is only one copy of the package loaded per
9951025
environment, while still allowing non-Node.js environments to benefit from
9961026
ES modules.
9971027

998-
### Approach 2: Isolate state in a CommonJS wrapper
1028+
### Approach 3: Isolate state in a CommonJS wrapper
9991029

10001030
If the package must provide both true ESM and CJS entry points in Node.js (for
10011031
example, to allow ESM consumers to use top-level `await`), the stateful parts
@@ -1241,6 +1271,7 @@ This field defines [subpath imports][] for the current package.
12411271
[folders as modules]: modules.md#folders-as-modules
12421272
[import maps]: https://github.com/WICG/import-maps
12431273
[load ECMAScript modules from CommonJS modules]: modules.md#loading-ecmascript-modules-using-require
1274+
[`require()` of ES modules]: modules.md#loading-ecmascript-modules-using-require
12441275
[merve]: https://github.com/anonrig/merve
12451276
[packages folder mapping]: https://github.com/WICG/import-maps#packages-via-trailing-slashes
12461277
[self-reference]: #self-referencing-a-package-using-its-name

0 commit comments

Comments
 (0)