Skip to content

Commit 16ec35d

Browse files
joyeecheungjoyeecheung
authored
Copy old documentation from package.md and fix links (#1)
1 parent 8d19ac5 commit 16ec35d

File tree

1 file changed

+273
-0
lines changed

1 file changed

+273
-0
lines changed

‎README.md

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# Node.js package shipping patterns
2+
3+
> [!NOTE]
4+
> This repository is currently under construction. It's meant to replace the sections in the Node.js package documentation for documenting package shipping patterns, the pros and cons, and guidelines for CJS to ESM migration.
5+
6+
## Previous documents from package.md in Node.js API documentation
7+
8+
> [!NOTE]
9+
> This is currently copied from the old package.md as-is. A lot of the information has been outdated since Node.js started to support `require(esm)`. We are still working on an update. Do not follow the documentation below for new packages for the time being.
10+
11+
Prior to the introduction of support for ES modules in Node.js, it was a common
12+
pattern for package authors to include both CommonJS and ES module JavaScript
13+
sources in their package, with `package.json` [`"main"`][] specifying the
14+
CommonJS entry point and `package.json` `"module"` specifying the ES module
15+
entry point.
16+
This enabled Node.js to run the CommonJS entry point while build tools such as
17+
bundlers used the ES module entry point, since Node.js ignored (and still
18+
ignores) the top-level `"module"` field.
19+
20+
Node.js can now run ES module entry points, and a package can contain both
21+
CommonJS and ES module entry points (either via separate specifiers such as
22+
`'pkg'` and `'pkg/es-module'`, or both at the same specifier via [Conditional
23+
exports][]). Unlike in the scenario where top-level `"module"` field is only used by bundlers,
24+
or ES module files are transpiled into CommonJS on the fly before evaluation by
25+
Node.js, the files referenced by the ES module entry point are evaluated as ES
26+
modules.
27+
28+
### Dual package hazard
29+
30+
When an application is using a package that provides both CommonJS and ES module
31+
sources, there is a risk of certain bugs if both versions of the package get
32+
loaded. This potential comes from the fact that the `pkgInstance` created by
33+
`const pkgInstance = require('pkg')` is not the same as the `pkgInstance`
34+
created by `import pkgInstance from 'pkg'` (or an alternative main path like
35+
`'pkg/module'`). This is the “dual package hazard,” where two versions of the
36+
same package can be loaded within the same runtime environment. While it is
37+
unlikely that an application or package would intentionally load both versions
38+
directly, it is common for an application to load one version while a dependency
39+
of the application loads the other version. This hazard can happen because
40+
Node.js supports intermixing CommonJS and ES modules, and can lead to unexpected
41+
behavior.
42+
43+
If the package main export is a constructor, an `instanceof` comparison of
44+
instances created by the two versions returns `false`, and if the export is an
45+
object, properties added to one (like `pkgInstance.foo = 3`) are not present on
46+
the other. This differs from how `import` and `require` statements work in
47+
all-CommonJS or all-ES module environments, respectively, and therefore is
48+
surprising to users. It also differs from the behavior users are familiar with
49+
when using transpilation via tools like [Babel][] or [`esm`][].
50+
51+
### Writing dual packages while avoiding or minimizing hazards
52+
53+
First, the hazard described in the previous section occurs when a package
54+
contains both CommonJS and ES module sources and both sources are provided for
55+
use in Node.js, either via separate main entry points or exported paths. A
56+
package might instead be written where any version of Node.js receives only
57+
CommonJS sources, and any separate ES module sources the package might contain
58+
are intended only for other environments such as browsers. Such a package
59+
would be usable by any version of Node.js, since `import` can refer to CommonJS
60+
files; but it would not provide any of the advantages of using ES module syntax.
61+
62+
A package might also switch from CommonJS to ES module syntax in a [breaking
63+
change](https://semver.org/) version bump. This has the disadvantage that the
64+
newest version of the package would only be usable in ES module-supporting
65+
versions of Node.js.
66+
67+
Every pattern has tradeoffs, but there are two broad approaches that satisfy the
68+
following conditions:
69+
70+
1. The package is usable via both `require` and `import`.
71+
2. The package is usable in both current Node.js and older versions of Node.js
72+
that lack support for ES modules.
73+
3. The package main entry point, e.g. `'pkg'` can be used by both `require` to
74+
resolve to a CommonJS file and by `import` to resolve to an ES module file.
75+
(And likewise for exported paths, e.g. `'pkg/feature'`.)
76+
4. The package provides named exports, e.g. `import { name } from 'pkg'` rather
77+
than `import pkg from 'pkg'; pkg.name`.
78+
5. The package is potentially usable in other ES module environments such as
79+
browsers.
80+
6. The hazards described in the previous section are avoided or minimized.
81+
82+
#### Approach #1: Use an ES module wrapper
83+
84+
Write the package in CommonJS or transpile ES module sources into CommonJS, and
85+
create an ES module wrapper file that defines the named exports. Using
86+
[Conditional exports][], the ES module wrapper is used for `import` and the
87+
CommonJS entry point for `require`.
88+
89+
```json
90+
// ./node_modules/pkg/package.json
91+
{
92+
"type": "module",
93+
"exports": {
94+
"import": "./wrapper.mjs",
95+
"require": "./index.cjs"
96+
}
97+
}
98+
```
99+
100+
The preceding example uses explicit extensions `.mjs` and `.cjs`.
101+
If your files use the `.js` extension, `"type": "module"` will cause such files
102+
to be treated as ES modules, just as `"type": "commonjs"` would cause them
103+
to be treated as CommonJS.
104+
See [Enabling ESM][].
105+
106+
```cjs
107+
// ./node_modules/pkg/index.cjs
108+
exports.name = 'value';
109+
```
110+
111+
```js
112+
// ./node_modules/pkg/wrapper.mjs
113+
import cjsModule from './index.cjs';
114+
export const name = cjsModule.name;
115+
```
116+
117+
In this example, the `name` from `import { name } from 'pkg'` is the same
118+
singleton as the `name` from `const { name } = require('pkg')`. Therefore `===`
119+
returns `true` when comparing the two `name`s and the divergent specifier hazard
120+
is avoided.
121+
122+
If the module is not simply a list of named exports, but rather contains a
123+
unique function or object export like `module.exports = function () { ... }`,
124+
or if support in the wrapper for the `import pkg from 'pkg'` pattern is desired,
125+
then the wrapper would instead be written to export the default optionally
126+
along with any named exports as well:
127+
128+
```js
129+
import cjsModule from './index.cjs';
130+
export const name = cjsModule.name;
131+
export default cjsModule;
132+
```
133+
134+
This approach is appropriate for any of the following use cases:
135+
136+
* The package is currently written in CommonJS and the author would prefer not
137+
to refactor it into ES module syntax, but wishes to provide named exports for
138+
ES module consumers.
139+
* The package has other packages that depend on it, and the end user might
140+
install both this package and those other packages. For example a `utilities`
141+
package is used directly in an application, and a `utilities-plus` package
142+
adds a few more functions to `utilities`. Because the wrapper exports
143+
underlying CommonJS files, it doesn't matter if `utilities-plus` is written in
144+
CommonJS or ES module syntax; it will work either way.
145+
* The package stores internal state, and the package author would prefer not to
146+
refactor the package to isolate its state management. See the next section.
147+
148+
A variant of this approach not requiring conditional exports for consumers could
149+
be to add an export, e.g. `"./module"`, to point to an all-ES module-syntax
150+
version of the package. This could be used via `import 'pkg/module'` by users
151+
who are certain that the CommonJS version will not be loaded anywhere in the
152+
application, such as by dependencies; or if the CommonJS version can be loaded
153+
but doesn't affect the ES module version (for example, because the package is
154+
stateless):
155+
156+
```json
157+
// ./node_modules/pkg/package.json
158+
{
159+
"type": "module",
160+
"exports": {
161+
".": "./index.cjs",
162+
"./module": "./wrapper.mjs"
163+
}
164+
}
165+
```
166+
167+
#### Approach #2: Isolate state
168+
169+
A [`package.json`][] file can define the separate CommonJS and ES module entry
170+
points directly:
171+
172+
```json
173+
// ./node_modules/pkg/package.json
174+
{
175+
"type": "module",
176+
"exports": {
177+
"import": "./index.mjs",
178+
"require": "./index.cjs"
179+
}
180+
}
181+
```
182+
183+
This can be done if both the CommonJS and ES module versions of the package are
184+
equivalent, for example because one is the transpiled output of the other; and
185+
the package's management of state is carefully isolated (or the package is
186+
stateless).
187+
188+
The reason that state is an issue is because both the CommonJS and ES module
189+
versions of the package might get used within an application; for example, the
190+
user's application code could `import` the ES module version while a dependency
191+
`require`s the CommonJS version. If that were to occur, two copies of the
192+
package would be loaded in memory and therefore two separate states would be
193+
present. This would likely cause hard-to-troubleshoot bugs.
194+
195+
Aside from writing a stateless package (if JavaScript's `Math` were a package,
196+
for example, it would be stateless as all of its methods are static), there are
197+
some ways to isolate state so that it's shared between the potentially loaded
198+
CommonJS and ES module instances of the package:
199+
200+
1. If possible, contain all state within an instantiated object. JavaScript's
201+
`Date`, for example, needs to be instantiated to contain state; if it were a
202+
package, it would be used like this:
203+
204+
```js
205+
import Date from 'date';
206+
const someDate = new Date();
207+
// someDate contains state; Date does not
208+
```
209+
210+
The `new` keyword isn't required; a package's function can return a new
211+
object, or modify a passed-in object, to keep the state external to the
212+
package.
213+
214+
2. Isolate the state in one or more CommonJS files that are shared between the
215+
CommonJS and ES module versions of the package. For example, if the CommonJS
216+
and ES module entry points are `index.cjs` and `index.mjs`, respectively:
217+
218+
```cjs
219+
// ./node_modules/pkg/index.cjs
220+
const state = require('./state.cjs');
221+
module.exports.state = state;
222+
```
223+
224+
```js
225+
// ./node_modules/pkg/index.mjs
226+
import state from './state.cjs';
227+
export {
228+
state,
229+
};
230+
```
231+
232+
Even if `pkg` is used via both `require` and `import` in an application (for
233+
example, via `import` in application code and via `require` by a dependency)
234+
each reference of `pkg` will contain the same state; and modifying that
235+
state from either module system will apply to both.
236+
237+
Any plugins that attach to the package's singleton would need to separately
238+
attach to both the CommonJS and ES module singletons.
239+
240+
This approach is appropriate for any of the following use cases:
241+
242+
* The package is currently written in ES module syntax and the package author
243+
wants that version to be used wherever such syntax is supported.
244+
* The package is stateless or its state can be isolated without too much
245+
difficulty.
246+
* The package is unlikely to have other public packages that depend on it, or if
247+
it does, the package is stateless or has state that need not be shared between
248+
dependencies or with the overall application.
249+
250+
Even with isolated state, there is still the cost of possible extra code
251+
execution between the CommonJS and ES module versions of a package.
252+
253+
As with the previous approach, a variant of this approach not requiring
254+
conditional exports for consumers could be to add an export, e.g.
255+
`"./module"`, to point to an all-ES module-syntax version of the package:
256+
257+
```json
258+
// ./node_modules/pkg/package.json
259+
{
260+
"type": "module",
261+
"exports": {
262+
".": "./index.cjs",
263+
"./module": "./index.mjs"
264+
}
265+
}
266+
```
267+
268+
[Babel]: https://babeljs.io/
269+
[Conditional exports]: https://nodejs.org/api/packages.html#conditional-exports
270+
[Enabling ESM]: https://nodejs.org/api/esm.html#enabling
271+
[`esm`]: https://github.com/standard-things/esm#readme
272+
[`main`]: https://nodejs.org/api/packages.html#main
273+
[`package.json`]: https://nodejs.org/api/packages.html#nodejs-packagejson-field-definitions

0 commit comments

Comments
 (0)