Skip to content

Commit 066f963

Browse files
mhdawsondanielleadams
authored andcommitted
doc: add initial doc on how to update cjs-module-lexer
Add some initial doc based on discussion with Guy Bedford. Signed-off-by: Michael Dawson <mdawson@devrus.com> PR-URL: #43255 Reviewed-By: Guy Bedford <guybedford@gmail.com>
1 parent 36e5684 commit 066f963

File tree

1 file changed

+59
-0
lines changed

1 file changed

+59
-0
lines changed
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Maintaining cjs-module-lexer
2+
3+
The [cjs-module-lexer](https://github.com/nodejs/node/tree/HEAD/deps/cjs-module-lexer)
4+
dependency is used within the Node.js ESM implementation to detect the
5+
named exports of a CommonJS module.
6+
7+
It is used within
8+
[`node:internal/modules/esm/translators`](https://github.com/nodejs/node/blob/HEAD/lib/internal/modules/esm/translators.js)
9+
in which both `internal/deps/cjs-module-lexer/lexer` and
10+
`internal/deps/cjs-module-lexer/dist/lexer` are required and used.
11+
12+
`internal/deps/cjs-module-lexer/lexer`
13+
is a regular JavaScript implementation that is
14+
used when WebAssembly is not available on a platform.
15+
`internal/deps/cjs-module-lexer/dist/lexer` is a faster
16+
implementation using WebAssembly which is generated from a
17+
C based implementation. These two paths
18+
resolve to the files in `deps/cjs-module-lexer` due to their
19+
inclusion in the `deps_files` entry in
20+
[node.gyp](https://github.com/nodejs/node/blob/master/node.gyp).
21+
22+
The two different versions of lexer.js are maintained in the
23+
[nodejs/cjs-module-lexer][] project.
24+
25+
In order to update the Node.js dependencies to use to a newer verion
26+
of cjs-module-lexer, complete the following steps:
27+
28+
* Clone [nodejs/cjs-module-lexer][]
29+
and check out the version that you want Node.js to use.
30+
* Follow the WASM build steps outlined in
31+
[wasm-build-steps](https://github.com/nodejs/cjs-module-lexer#wasm-build-steps).
32+
This will generate the WASM based dist/lexer.js file.
33+
* Preserving the same directory structure, copy the following files over
34+
to `deps/cjs-module-lexer` directory where you have checked out Node.js.
35+
36+
```text
37+
β”œβ”€β”€ CHANGELOG.md
38+
β”œβ”€β”€ dist
39+
β”‚Β Β  β”œβ”€β”€ lexer.js
40+
β”‚Β Β  └── lexer.mjs
41+
β”œβ”€β”€ lexer.js
42+
β”œβ”€β”€ LICENSE
43+
β”œβ”€β”€ package.json
44+
└── README.md
45+
```
46+
47+
* Update the link to the cjs-module-lexer in the list at the end of
48+
[doc/api/esm.md](../api/esm.md)
49+
to point to the updated version.
50+
51+
* Create a PR, adding the files in the deps/cjs-module-lexer that
52+
were modified.
53+
54+
If updates are needed to cjs-module-lexer for Node.js, first PR
55+
those updates into
56+
[nodejs/cjs-module-lexer][],
57+
request a release and then pull in the updated version once available.
58+
59+
[nodejs/cjs-module-lexer]: https://github.com/nodejs/cjs-module-lexer

0 commit comments

Comments
Β (0)