Skip to content

[v12 backport] ESM (named exports for CJS, package.json docs, subpath export patterns, warning removal) #35757

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.

Sign up for GitHub

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

Closed
aduh95 wants to merge 17 commits into from
Closed

[v12 backport] ESM (named exports for CJS, package.json docs, subpath export patterns, warning removal) #35757

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
21fca91
module: named exports for CJS via static analysis
guybedford May 15, 2020
ade34f3
module: refine module type mismatch error cases
guybedford Sep 30, 2020
57b6119
module: update to cjs-module-lexer@0.4.0
guybedford Oct 4, 2020
4c714c7
doc: rename module pages
aduh95 Aug 7, 2020
b517ae8
doc: move package config docs to separate page
aduh95 Aug 7, 2020
cc303a9
doc: document support for package.json fields
aduh95 Aug 7, 2020
7b76e75
module: exports pattern support
guybedford Aug 12, 2020
55d15e6
doc: edit subpath export patterns introduction
Trott Sep 18, 2020
3b49965
doc: refine require/import conditions constraints
guybedford Sep 23, 2020
ee644b4
doc: packages docs feedback
guybedford Sep 27, 2020
728ddbf
doc: copyedit packages.md
Trott Sep 30, 2020
e1958d5
doc: fix conditional exports flag removal version
aduh95 Sep 30, 2020
6c27021
doc: add history entry for exports patterns
aduh95 Sep 29, 2020
e8a7201
doc,esm: add history support info
aduh95 Sep 28, 2020
63fffcf
module: remove experimental modules warning
guybedford Feb 26, 2020
18c9216
doc,esm: document experimental warning removal
aduh95 Oct 22, 2020
3e18962
esm: use "node:" namespace for builtins
guybedford Sep 28, 2020
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
Prev Previous commit
Next Next commit
doc: document support for package.json fields 
Fixes: #33143

PR-URL: #34970
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
  • Loading branch information
@aduh95
aduh95 committed Oct 23, 2020
commit cc303a9bb048d0cb1f30a7267ba46ce2910da882
17 changes: 9 additions & 8 deletions doc/api/errors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1357,13 +1357,13 @@ An invalid or unknown file encoding was passed.
<a id="ERR_INVALID_PACKAGE_CONFIG"></a>
### `ERR_INVALID_PACKAGE_CONFIG`

An invalid `package.json` file was found which failed parsing.
An invalid [`package.json`][] file was found which failed parsing.

<a id="ERR_INVALID_PACKAGE_TARGET"></a>
### `ERR_INVALID_PACKAGE_TARGET`

The `package.json` [exports][] field contains an invalid target mapping value
for the attempted module resolution.
The `package.json` [`"exports"`][] field contains an invalid target mapping
value for the attempted module resolution.

<a id="ERR_INVALID_PERFORMANCE_MARK"></a>
### `ERR_INVALID_PERFORMANCE_MARK`
Expand Down Expand Up @@ -1686,13 +1686,13 @@ A given value is out of the accepted range.
<a id="ERR_PACKAGE_IMPORT_NOT_DEFINED"></a>
### `ERR_PACKAGE_IMPORT_NOT_DEFINED`

The `package.json` ["imports" field][] does not define the given internal
The `package.json` [`"imports"`][] field does not define the given internal
package specifier mapping.

<a id="ERR_PACKAGE_PATH_NOT_EXPORTED"></a>
### `ERR_PACKAGE_PATH_NOT_EXPORTED`

The `package.json` [exports][] field does not export the requested subpath.
The `package.json` [`"exports"`][] field does not export the requested subpath.
Because exports are encapsulated, private internal modules that are not exported
cannot be imported through the package resolution, unless using an absolute URL.

Expand Down Expand Up @@ -2057,7 +2057,7 @@ signal (such as [`subprocess.kill()`][]).

`import` a directory URL is unsupported. Instead,
[self-reference a package using its name][] and [define a custom subpath][] in
the `"exports"` field of the `package.json` file.
the [`"exports"`][] field of the [`package.json`][] file.

<!-- eslint-skip -->
```js
Expand Down Expand Up @@ -2529,7 +2529,8 @@ closed.
[crypto digest algorithm]: crypto.html#crypto_crypto_gethashes
[domains]: domain.html
[event emitter-based]: events.html#events_class_eventemitter
[exports]: packages.html#packages_package_entry_points
[`package.json`]: packages.html#packages_node_js_package_json_field_definitions
[`"exports"`]: packages.html#packages_exports
[file descriptors]: https://en.wikipedia.org/wiki/File_descriptor
[policy]: policy.html
[stream-based]: stream.html
Expand All @@ -2539,4 +2540,4 @@ closed.
[vm]: vm.html
[self-reference a package using its name]: packages.html#packages_self_referencing_a_package_using_its_name
[define a custom subpath]: packages.html#packages_subpath_exports
["imports" field]: packages.html#packages_internal_package_imports
[`"imports"`]: packages.html#packages_imports
11 changes: 7 additions & 4 deletions doc/api/esm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ specifier resolution, and default behavior.

Node.js treats JavaScript code as CommonJS modules by default.
Authors can tell Node.js to treat JavaScript code as ECMAScript modules
via the `.mjs` file extension, the `package.json` `"type"` field, or the
via the `.mjs` file extension, the `package.json` [`"type"`][] field, or the
`--input-type` flag. See
[Modules: Packages](packages.html#packages_determining_module_system) for more
details.
Expand Down Expand Up @@ -260,9 +260,9 @@ can either be an URL-style relative path like `'./file.mjs'` or a package name
like `'fs'`.

Like in CommonJS, files within packages can be accessed by appending a path to
the package name; unless the package’s `package.json` contains an `"exports"`
field, in which case files within packages need to be accessed via the path
defined in `"exports"`.
the package name; unless the package’s [`package.json`][] contains an
[`"exports"`][] field, in which case files within packages need to be accessed
via the path defined in [`"exports"`][].

```js
import { sin, cos } from 'geometry/trigonometry-functions.mjs';
Expand Down Expand Up @@ -1223,3 +1223,6 @@ success!
[6.1.7 Array Index]: https://tc39.es/ecma262/#integer-index
[Top-Level Await]: https://github.com/tc39/proposal-top-level-await
[Core modules]: modules.html#modules_core_modules
[`package.json`]: packages.html#packages_node_js_package_json_field_definitions
[`"exports"`]: packages.html#packages_exports
[`"type"`]: packages.html#packages_type
12 changes: 7 additions & 5 deletions doc/api/modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -391,8 +391,8 @@ directories, and then provide a single entry point to those directories.
There are three ways in which a folder may be passed to `require()` as
an argument.

The first is to create a `package.json` file in the root of the folder,
which specifies a `main` module. An example `package.json` file might
The first is to create a [`package.json`][] file in the root of the folder,
which specifies a `main` module. An example [`package.json`][] file might
look like this:

```json
Expand All @@ -406,10 +406,10 @@ If this was in a folder at `./some-library`, then

This is the extent of the awareness of `package.json` files within Node.js.

If there is no `package.json` file present in the directory, or if the
`'main'` entry is missing or cannot be resolved, then Node.js
If there is no [`package.json`][] file present in the directory, or if the
[`"main"`][] entry is missing or cannot be resolved, then Node.js
will attempt to load an `index.js` or `index.node` file out of that
directory. For example, if there was no `package.json` file in the above
directory. For example, if there was no [`package.json`][] file in the previous
example, then `require('./some-library')` would attempt to load:

* `./some-library/index.js`
Expand Down Expand Up @@ -1154,3 +1154,5 @@ consists of the following keys:
[`Error.prepareStackTrace(error, trace)`]: https://v8.dev/docs/stack-trace-api#customizing-stack-traces
[`SourceMap`]: modules.html#modules_class_module_sourcemap
[Source map v3 format]: https://sourcemaps.info/spec.html#h.mofvlxcwqzej
[`package.json`]: packages.html#packages_node_js_package_json_field_definitions
[`"main"`]: packages.html#packages_main
Loading