Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add initial doc on how to update cjs-module-lexer #43255

Closed
wants to merge 21 commits into from
Closed
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
5c1eb78
doc: add initial doc on how to update cjs-module-lexer
mhdawson May 30, 2022
1f585a8
fixup
mhdawson May 30, 2022
a64872f
squash: address comments
mhdawson May 30, 2022
7fb464d
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson May 31, 2022
5bb755c
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson May 31, 2022
5308a8f
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson May 31, 2022
f8cb6f5
address comments
mhdawson May 31, 2022
334ed03
fixup
mhdawson May 31, 2022
55b4b1d
fixup
mhdawson May 31, 2022
9dac62d
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson May 31, 2022
277f5bb
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson Jun 1, 2022
c9876b1
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson Jun 1, 2022
bf1d2be
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson Jun 1, 2022
d27e418
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson Jun 1, 2022
fb2b273
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson Jun 1, 2022
3d91e29
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson Jun 1, 2022
b4ddcb8
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson Jun 1, 2022
7de0eae
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson Jun 13, 2022
5a25b9d
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson Jun 13, 2022
6d33ab2
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson Jun 13, 2022
df2c15f
Update doc/contributing/maintaining-cjs-module-lexer.md
mhdawson Jun 13, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions doc/contributing/maintaining-cjs-module-lexer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Maintaining cjs-module-lexer

The [cjs-module-lexer](https://github.com/nodejs/node/tree/HEAD/deps/cjs-module-lexer)
dependency is used within the Node.js ESM implementation to detect the
named exports of a CommonJS module.

It is used within
[`node:internal/modules/esm/translators`](https://github.com/nodejs/node/blob/HEAD/lib/internal/modules/esm/translators.js)
in which both `internal/deps/cjs-module-lexer/lexer` and
`internal/deps/cjs-module-lexer/dist/lexer` are required and used.

`internal/deps/cjs-module-lexer/lexer`
is a regular JavaScript implementation that is
used when WebAssembly is not available on a platform.
`internal/deps/cjs-module-lexer/dist/lexer` is a faster
implementation using WebAssembly which is generated from a
C based implementation. These two paths
resolve to the files in `deps/cjs-module-lexer` due to their
inclusion in the `deps_files` entry in
[node.gyp](https://github.com/nodejs/node/blob/master/node.gyp).

The two different versions of lexer.js are maintained in the
[nodejs/cjs-module-lexer][] project.

In order to update the Node.js dependencies to use to a newer verion
of cjs-module-lexer, complete the following steps:

* Clone [nodejs/cjs-module-lexer][]
and check out the version that you want Node.js to use.
* Follow the WASM build steps outlined in
[wasm-build-steps](https://github.com/nodejs/cjs-module-lexer#wasm-build-steps).
This will generate the WASM based dist/lexer.js file.
* Preserving the same directory structure, copy the following files over
to `deps/cjs-module-lexer` directory where you have checked out Node.js.

```text
├── CHANGELOG.md
├── dist
│   ├── lexer.js
│   └── lexer.mjs
├── lexer.js
├── LICENSE
├── package.json
└── README.md
```

* Update the link to the cjs-module-lexer in the list at the end of
[doc/api/esm.md](../api/esm.md)
to point to the updated version.

* Create a PR, adding the files in the deps/cjs-module-lexer that
were modified.

If updates are needed to cjs-module-lexer for Node.js, first PR
those updates into
[nodejs/cjs-module-lexer][],
request a release and then pull in the updated version once available.
mhdawson marked this conversation as resolved.
Show resolved Hide resolved

[nodejs/cjs-module-lexer]: https://github.com/nodejs/cjs-module-lexer