mirror of
https://github.com/nodejs/node.git
synced 2025-04-28 13:40:37 +00:00
doc: remove Corepack documentation
PR-URL: https://github.com/nodejs/node/pull/57635 Reviewed-By: Jordan Harband <ljharb@gmail.com> Reviewed-By: Zeyu "Alex" Yang <himself65@outlook.com> Reviewed-By: Chemi Atlow <chemi@atlow.co.il> Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com> Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
This commit is contained in:
Antoine du Hamel
GitHub
parent
c922bd812c
commit
af75d04a76
@ -12,139 +12,10 @@ added:
|
||||
|
||||
> Stability: 1 - Experimental
|
||||
|
||||
_[Corepack][Corepack repository]_ 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, download it if needed,
|
||||
and finally run it.
|
||||
Documentation for this tool can be found on the [Corepack repository][].
|
||||
|
||||
Despite Corepack being distributed with default installs of Node.js, the package
|
||||
managers managed by Corepack are not part of the Node.js distribution and:
|
||||
managers managed by Corepack are not part of the Node.js distribution, and
|
||||
Corepack itself will no longer be distributed with future versions of Node.js.
|
||||
|
||||
* Upon first use, Corepack downloads the latest version from the network.
|
||||
* Any required updates (related to security vulnerabilities or otherwise) are
|
||||
out of scope of the Node.js project. If necessary end users must figure out
|
||||
how to update on their own.
|
||||
|
||||
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, 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, run
|
||||
[`corepack disable`][] to remove the proxies from your system (and consider
|
||||
opening 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.
|
||||
|
||||
You can use [`corepack use`][] to ask Corepack to update your local
|
||||
`package.json` to use the package manager of your choice:
|
||||
|
||||
```bash
|
||||
corepack use pnpm@7.x # sets the latest 7.x version in the package.json
|
||||
corepack use yarn@* # sets the latest version in the package.json
|
||||
```
|
||||
|
||||
### 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 overridden by running the [`corepack install`][] command along with the
|
||||
package manager version you wish to set:
|
||||
|
||||
```bash
|
||||
corepack install --global yarn@x.y.z
|
||||
```
|
||||
|
||||
Alternately, a tag or range may be used:
|
||||
|
||||
```bash
|
||||
corepack install --global pnpm@*
|
||||
corepack install --global yarn@stable
|
||||
```
|
||||
|
||||
### 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 pack`][] 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 `pack` command has [various flags][]. Consult the detailed
|
||||
[Corepack documentation][] for more information.
|
||||
|
||||
## 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 interact with npm?
|
||||
|
||||
While Corepack could support npm like any other package manager, its
|
||||
shims aren't 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; 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.
|
||||
|
||||
* Add the `--force` flag to `npm install`; this will tell npm that it's fine to
|
||||
override binaries, but you'll erase the Corepack ones in the process. (Run
|
||||
[`corepack enable`][] to add them back.)
|
||||
|
||||
[Corepack documentation]: https://github.com/nodejs/corepack#readme
|
||||
[Corepack repository]: https://github.com/nodejs/corepack
|
||||
[Yarn]: https://yarnpkg.com
|
||||
[`"packageManager"`]: packages.md#packagemanager
|
||||
[`corepack disable`]: https://github.com/nodejs/corepack#corepack-disable--name
|
||||
[`corepack enable`]: https://github.com/nodejs/corepack#corepack-enable--name
|
||||
[`corepack install`]: https://github.com/nodejs/corepack#corepack-install--g--global---all--nameversion
|
||||
[`corepack pack`]: https://github.com/nodejs/corepack#corepack-pack---all--nameversion
|
||||
[`corepack use`]: https://github.com/nodejs/corepack#corepack-use-nameversion
|
||||
[`package.json`]: packages.md#nodejs-packagejson-field-definitions
|
||||
[pnpm]: https://pnpm.io
|
||||
[supported binaries]: #supported-package-managers
|
||||
[supported package manager]: #supported-package-managers
|
||||
[various flags]: https://github.com/nodejs/corepack#utility-commands
|
||||
|
||||
@ -21,7 +21,6 @@
|
||||
* [Cluster](cluster.md)
|
||||
* [Command-line options](cli.md)
|
||||
* [Console](console.md)
|
||||
* [Corepack](corepack.md)
|
||||
* [Crypto](crypto.md)
|
||||
* [Debugger](debugger.md)
|
||||
* [Deprecated APIs](deprecations.md)
|
||||
|
||||
@ -259,21 +259,6 @@ 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
|
||||
@ -905,8 +890,6 @@ 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,
|
||||
@ -971,33 +954,6 @@ via `require()`](modules.md#folders-as-modules).
|
||||
require('./path/to/directory');
|
||||
```
|
||||
|
||||
### `"packageManager"`
|
||||
|
||||
<!-- YAML
|
||||
added:
|
||||
- v16.9.0
|
||||
- v14.19.0
|
||||
-->
|
||||
|
||||
> 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 be 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 other 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
|
||||
@ -1137,7 +1093,6 @@ This field defines [subpath imports][] for the current package.
|
||||
|
||||
[CommonJS]: modules.md
|
||||
[Conditional exports]: #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
|
||||
@ -1148,7 +1103,6 @@ This field defines [subpath imports][] for the current package.
|
||||
[`"imports"`]: #imports
|
||||
[`"main"`]: #main
|
||||
[`"name"`]: #name
|
||||
[`"packageManager"`]: #packagemanager
|
||||
[`"type"`]: #type
|
||||
[`--conditions` / `-C` flag]: #resolving-user-conditions
|
||||
[`--no-addons` flag]: cli.md#--no-addons
|
||||
@ -1163,7 +1117,6 @@ This field defines [subpath imports][] for the current package.
|
||||
[self-reference]: #self-referencing-a-package-using-its-name
|
||||
[subpath exports]: #subpath-exports
|
||||
[subpath imports]: #subpath-imports
|
||||
[supported package managers]: corepack.md#supported-package-managers
|
||||
[the dual CommonJS/ES module packages section]: #dual-commonjses-module-packages
|
||||
[the full specifier path]: esm.md#mandatory-file-extensions
|
||||
[the package examples repository]: https://github.com/nodejs/package-examples
|
||||
|
||||
@ -45,7 +45,7 @@ const linkedHtmls = [...new Set(links)].map((link) => link.match(re)[1])
|
||||
const expectedJsons = linkedHtmls
|
||||
.map((name) => name.replace('.html', '.json'));
|
||||
const expectedDocs = linkedHtmls.concat(expectedJsons);
|
||||
const renamedDocs = ['policy.json', 'policy.html'];
|
||||
const renamedDocs = ['corepack.json', 'corepack.html', 'policy.json', 'policy.html'];
|
||||
const skipedDocs = ['quic.json', 'quic.html'];
|
||||
|
||||
// Test that all the relative links in the TOC match to the actual documents.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user