diff options
Diffstat (limited to 'doc/api/packages.md')
| -rw-r--r-- | doc/api/packages.md | 44 |
1 files changed, 44 insertions, 0 deletions
diff --git a/doc/api/packages.md b/doc/api/packages.md index 2e3a731727f..c5c4a665f2e 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -155,6 +155,21 @@ For completeness there is also `--input-type=commonjs`, for explicitly running string input as CommonJS. This is the default behavior if `--input-type` is unspecified. +## Determining package manager + +> Stability: 1 - Experimental + +While all Node.js projects are expected to be installable by all package +managers once published, their development teams are often required to use one +specific package manager. To make this process easier, Node.js ships with a +tool called [Corepack][] that aims to make all package managers transparently +available in your environment - provided you have Node.js installed. + +By default Corepack won't enforce any specific package manager and will use +the generic "Last Known Good" versions associated with each Node.js release, +but you can improve this experience by setting the [`"packageManager"`][] field +in your project's `package.json`. + ## Package entry points In a package’s `package.json` file, two fields can define entry points for a @@ -973,6 +988,8 @@ The following fields in `package.json` files are used in Node.js: 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. +* [`"packageManager"`][] - The package manager recommended when contributing to + the package. Leveraged by the [Corepack][] shims. * [`"type"`][] - The package type determining whether to load `.js` files as CommonJS or ES modules. * [`"exports"`][] - Package exports and conditional exports. When present, @@ -1032,6 +1049,30 @@ 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. +### `"packageManager"` +<!-- YAML +added: REPLACEME +--> + +> Stability: 1 - Experimental + +* Type: {string} + +```json +{ + "packageManager": "<package manager name>@<version>" +} +``` + +The `"packageManager"` field defines which package manager is expected to be +used when working on the current project. It can set to any of the +[supported package managers][], and will ensure that your teams use the exact +same package manager versions without having to install anything else than +Node.js. + +This field is currently experimental and needs to be opted-in; check the +[Corepack][] page for details about the procedure. + ### `"type"` <!-- YAML added: v12.0.0 @@ -1164,6 +1205,7 @@ This field defines [subpath imports][] for the current package. [Babel]: https://babeljs.io/ [CommonJS]: modules.md [Conditional exports]: #packages_conditional_exports +[Corepack]: corepack.md [ES module]: esm.md [ES modules]: esm.md [Node.js documentation for this section]: https://github.com/nodejs/node/blob/HEAD/doc/api/packages.md#conditions-definitions @@ -1171,6 +1213,7 @@ This field defines [subpath imports][] for the current package. [`"imports"`]: #packages_imports [`"main"`]: #packages_main [`"name"`]: #packages_name +[`"packageManager"`]: #packages_packagemanager [`"type"`]: #packages_type [`--no-addons` flag]: cli.md#cli_no_addons [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#errors_err_package_path_not_exported @@ -1180,5 +1223,6 @@ This field defines [subpath imports][] for the current package. [self-reference]: #packages_self_referencing_a_package_using_its_name [subpath exports]: #packages_subpath_exports [subpath imports]: #packages_subpath_imports +[supported package managers]: corepack.md#corepack_supported_package_managers [the dual CommonJS/ES module packages section]: #packages_dual_commonjs_es_module_packages [the full specifier path]: esm.md#esm_mandatory_file_extensions |