Skip to content

Commit

Permalink
doc: document support for package.json fields
Browse files Browse the repository at this point in the history
Fixes: #33143

Backport-PR-URL: #35757
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 authored and MylesBorins committed Nov 16, 2020
1 parent 7c1700e commit d6a13a9
Show file tree
Hide file tree
Showing 4 changed files with 276 additions and 142 deletions.
17 changes: 9 additions & 8 deletions doc/api/errors.md
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
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
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

0 comments on commit d6a13a9

Please sign in to comment.