diff options
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/corepack.md | 119 | ||||
-rw-r--r-- | doc/api/index.md | 1 | ||||
-rw-r--r-- | doc/api/packages.md | 44 |
3 files changed, 164 insertions, 0 deletions
diff --git a/doc/api/corepack.md b/doc/api/corepack.md new file mode 100644 index 00000000000..1e30256b491 --- /dev/null +++ b/doc/api/corepack.md @@ -0,0 +1,119 @@ +# Corepack + +<!-- introduced_in=REPLACEME --> +<!-- type=misc --> + +> Stability: 1 - Experimental + +_[Corepack][]_ is an experimental tool to help with +managing versions of your package managers. It exposes binary proxies for +each [supported package manager][] that, when called, will identify whatever +package manager is configured for the current project, transparently install +it if needed, and finally run it without requiring explicit user interactions. + +This feature simplifies two core workflows: + +* It eases new contributor onboarding, since they won't have to follow + system-specific installation processes anymore just to have the package + manager you want them to. + +* It allows you to ensure that everyone in your team will use exactly the + package manager version you intend them to, without them having to + manually synchronize it each time you need to make an update. + +## Workflows + +### Enabling the feature + +Due to its experimental status, Corepack currently needs to be explicitly +enabled to have any effect. To do that simply run [`corepack enable`][], which +will set up the symlinks in your environment, next to the `node` binary +(and overwrite the existing symlinks if necessary). + +From this point forward, any call to the [supported binaries][] will work +without further setup. Should you experience a problem, just run +[`corepack disable`][] to remove the proxies from your system (and consider +opening up an issue on the [Corepack repository][] to let us know). + +### Configuring a package + +The Corepack proxies will find the closest [`package.json`][] file in your +current directory hierarchy to extract its [`"packageManager"`][] property. + +If the value corresponds to a [supported package manager][], Corepack will make +sure that all calls to the relevant binaries are run against the requested +version, downloading it on demand if needed, and aborting if it cannot be +successfully retrieved. + +### Upgrading the global versions + +When running outside of an existing project (for example when running +`yarn init`), Corepack will by default use predefined versions roughly +corresponding to the latest stable releases from each tool. Those versions can +be easily overriden by running the [`corepack prepare`][] command along with the +package manager version you wish to set: + +```bash +corepack prepare yarn@x.y.z --activate +``` + +### Offline workflow + +Many production environments don't have network access. Since Corepack +usually downloads the package manager releases straight from their registries, +it can conflict with such environments. To avoid that happening, call the +[`corepack prepare`][] command while you still have network access (typically at +the same time you're preparing your deploy image). This will ensure that the +required package managers are available even without network access. + +The `prepare` command has [various flags][], consult the detailed +[Corepack documentation][] for more information on the matter. + +## Supported package managers + +The following binaries are provided through Corepack: + +| Package manager | Binary names | +| --------------- | -------------- | +| [Yarn][] | `yarn`, `yarnpkg` | +| [pnpm][] | `pnpm`, `pnpx` | + +## Common questions + +### How does Corepack currently interact with npm? + +While Corepack could easily support npm like any other package manager, its +shims aren't currently enabled by default. This has a few consequences: + +* It's always possible to run a `npm` command within a project configured to +be used with another package manager, since Corepack cannot intercept it. + +* While `npm` is a valid option in the [`"packageManager"`][] property, the +lack of shim will cause the global npm to be used. + +### Running `npm install -g yarn` doesn't work + +npm prevents accidentally overriding the Corepack binaries when doing a global +install. To avoid this problem, consider one of the following options: + +* Don't run this command anymore; Corepack will provide the package manager +binaries anyway and will ensure that the requested versions are always +available, so installing the package managers explicitly isn't needed anymore. + +* Add the `--force` to `npm install`; this will tell npm that it's fine to +override binaries, but you'll erase the Corepack ones in the process (should +that happen, run [`corepack enable`][] again to add them back). + +[Corepack]: https://github.com/nodejs/corepack +[Corepack documentation]: https://github.com/nodejs/corepack#readme +[Corepack repository]: https://github.com/nodejs/corepack +[Yarn]: https://yarnpkg.com +[`"packageManager"`]: packages.md#packages_packagemanager +[`corepack disable`]: https://github.com/nodejs/corepack#corepack-disable--name +[`corepack enable`]: https://github.com/nodejs/corepack#corepack-enable--name +[`corepack prepare`]: https://github.com/nodejs/corepack#corepack-prepare--nameversion +[`package.json`]: packages.md#packages_node_js_package_json_field_definitions +[pnpm]: https://pnpm.js.org +[supported binaries]: #corepack_supported_package_managers +[supported package manager]: #corepack_supported_package_managers +[various flags]: https://github.com/nodejs/corepack#utility-commands diff --git a/doc/api/index.md b/doc/api/index.md index 448f6d599fc..8ea274ec47e 100644 --- a/doc/api/index.md +++ b/doc/api/index.md @@ -21,6 +21,7 @@ * [Cluster](cluster.md) * [Command-line options](cli.md) * [Console](console.md) +* [Corepack](corepack.md) * [Crypto](crypto.md) * [Debugger](debugger.md) * [Deprecated APIs](deprecations.md) diff --git a/doc/api/packages.md b/doc/api/packages.md index 0278b649087..09acf5a5490 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -156,6 +156,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 @@ -1008,6 +1023,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, @@ -1067,6 +1084,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 @@ -1199,6 +1240,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 @@ -1206,6 +1248,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 [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#errors_err_package_path_not_exported [`esm`]: https://github.com/standard-things/esm#readme @@ -1215,5 +1258,6 @@ This field defines [subpath imports][] for the current package. [subpath exports]: #packages_subpath_exports [subpath imports]: #packages_subpath_imports [subpath patterns]: #packages_subpath_patterns +[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 |