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.

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

Jump to bottom

doc: add version metadata for packages features #37289

Merged
merged 1 commit into from
Feb 13, 2021
Merged

doc: add version metadata for packages features #37289

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
50 changes: 49 additions & 1 deletion doc/api/packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@ changes:
- v12.20.0
pr-url: https://github.com/nodejs/node/pull/34718
description: Add support for `"exports"` patterns.
- version: v14.6.0
- version:
- v14.6.0
- v12.19.0
pr-url: https://github.com/nodejs/node/pull/34117
description: Add package `"imports"` field.
- version:
Expand Down Expand Up @@ -136,6 +138,9 @@ package:
`"commonjs"` package).

### `--input-type` flag
<!-- YAML
added: v12.0.0
-->

Strings passed in as an argument to `--eval` (or `-e`), or piped to `node` via
`STDIN`, are treated as [ES modules][] when the `--input-type=module` flag
Expand Down Expand Up @@ -253,6 +258,9 @@ absolute subpath of the package such as
`require('/path/to/node_modules/pkg/subpath.js')` will still load `subpath.js`.

### Subpath exports
<!-- YAML
added: v12.7.0
-->

When using the [`"exports"`][] field, custom subpaths can be defined along
with the main entry point by treating the main entry point as the
Expand Down Expand Up @@ -283,6 +291,11 @@ import submodule from 'es-module-package/private-module.js';
```

### Subpath imports
<!--YAML
added:
- v14.6.0
- v12.19.0
-->

In addition to the [`"exports"`][] field, it is possible to define internal
package import maps that only apply to import specifiers from within the package
Expand Down Expand Up @@ -320,6 +333,11 @@ The resolution rules for the imports field are otherwise
analogous to the exports field.

### Subpath patterns
<!--YAML
added:
- v14.13.0
- v12.19.0
-->

For packages with a small number of exports or imports, we recommend
explicitly listing each exports subpath entry. But for packages that have
Expand Down Expand Up @@ -407,6 +425,9 @@ The benefit of patterns over folder exports is that packages can always be
imported by consumers without subpath file extensions being necessary.

### Exports sugar
<!--YAML
added: v12.11.0
-->

If the `"."` export is the only export, the [`"exports"`][] field provides sugar
for this case being the direct [`"exports"`][] field value.
Expand All @@ -431,6 +452,17 @@ can be written:
```

### Conditional exports
<!--YAML
added:
- v13.2.0
- v12.16.0
changes:
- version:
- v13.7.0
- v12.16.0
pr-url: https://github.com/nodejs/node/pull/31001
description: Unflag conditional exports.
-->

Conditional exports provide a way to map to different paths depending on
certain conditions. They are supported for both CommonJS and ES module imports.
Expand Down Expand Up @@ -529,6 +561,11 @@ the remaining conditions of the parent condition. In this way nested
conditions behave analogously to nested JavaScript `if` statements.

### Resolving user conditions
<!-- YAML
added:
- v14.9.0
- v12.19.0
-->

When running Node.js, custom user conditions can be added with the
`--conditions` flag:
Expand Down Expand Up @@ -590,6 +627,17 @@ The above definitions may be moved to a dedicated conditions registry in due
course.

### Self-referencing a package using its name
<!--YAML
added:
- v13.1.0
- v12.16.0
changes:
- version:
- v13.6.0
- v12.16.0
pr-url: https://github.com/nodejs/node/pull/31002
description: Unflag self-referencing a package using its name.
-->

Within a package, the values defined in the package’s
`package.json` [`"exports"`][] field can be referenced via the package’s name.
Expand Down