Skip to content

Commit

Permalink
doc: update package.json field definitions
Browse files Browse the repository at this point in the history
Only imports has the experimental status right now but technically all
ESM related features are currently experimental. The list also doesn't
appear to be in any specific order so I've grouped the experimental
features together.

PR-URL: #35741
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Ujjwal Sharma <ryzokuken@disroot.org>
  • Loading branch information
MylesBorins authored and targos committed Nov 3, 2020
1 parent 66da122 commit 6590f8c
Showing 1 changed file with 30 additions and 26 deletions.
56 changes: 30 additions & 26 deletions doc/api/packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -834,12 +834,12 @@ The following fields in `package.json` files are used in Node.js:

* [`"name"`][] - Relevant when using named imports within a package. Also used
by package managers as the name of the package.
* [`"main"`][] - The default module when loading the package, if exports is not
specified, and in versions of Node.js prior to the introduction of exports.
* [`"type"`][] - The package type determining whether to load `.js` files as
CommonJS or ES modules.
* [`"exports"`][] - Package exports and conditional exports. When present,
limits which submodules can be loaded from within the package.
* [`"main"`][] - The default module when loading the package, if exports is not
specified, and in versions of Node.js prior to the introduction of exports.
* [`"imports"`][] - Package imports, for use by modules within the package
itself.

Expand Down Expand Up @@ -871,6 +871,30 @@ _npm_ registry requires a name that satisfies
The `"name"` field can be used in addition to the [`"exports"`][] field to
[self-reference][] a package using its name.

### `"main"`
<!-- YAML
added: v0.4.0
-->

* Type: {string}

```json
{
"main": "./main.js"
}
```

The `"main"` field defines the script that is used when the [package directory
is loaded via `require()`](modules.md#modules_folders_as_modules). Its value
is a path.

```js
require('./path/to/directory'); // This resolves to ./path/to/directory/main.js.
```

When a package has an [`"exports"`][] field, this will take precedence over the
`"main"` field when importing the package by name.

### `"type"`
<!-- YAML
added: v12.0.0
Expand All @@ -882,6 +906,8 @@ changes:
description: Unflag `--experimental-modules`.
-->

> Stability: 1 - Experimental

* Type: {string}

The `"type"` field defines the module format that Node.js uses for all
Expand Down Expand Up @@ -948,6 +974,8 @@ changes:
description: Implement conditional exports.
-->

> Stability: 1 - Experimental

* Type: {Object} | {string} | {string[]}

```json
Expand All @@ -969,30 +997,6 @@ referenced via `require` or via `import`.
All paths defined in the `"exports"` must be relative file URLs starting with
`./`.

### `"main"`
<!-- YAML
added: v0.4.0
-->

* Type: {string}

```json
{
"main": "./main.js"
}
```

The `"main"` field defines the script that is used when the [package directory
is loaded via `require()`](modules.md#modules_folders_as_modules). Its value
is interpreted as a path.

```js
require('./path/to/directory'); // This resolves to ./path/to/directory/main.js.
```

When a package has an [`"exports"`][] field, this will take precedence over the
`"main"` field when importing the package by name.

### `"imports"`
<!-- YAML
added: v14.6.0
Expand Down

0 comments on commit 6590f8c

Please sign in to comment.