You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: deps/corepack/README.md
+103-46
Original file line number
Diff line number
Diff line change
@@ -1,21 +1,30 @@
1
1
# <imgsrc="./icon.svg"height="25" /> corepack
2
2
3
-
Corepack is a zero-runtime-dependency Node.js script that acts as a bridge between Node.js projects and the package managers they are intended to be used with during development. In practical terms, **Corepack will let you use Yarn and pnpm without having to install them** - just like what currently happens with npm, which is shipped by Node.js by default.
3
+
Corepack is a zero-runtime-dependency Node.js script that acts as a bridge
4
+
between Node.js projects and the package managers they are intended to be used
5
+
with during development. In practical terms, **Corepack will let you use Yarn
6
+
and pnpm without having to install them** - just like what currently happens
7
+
with npm, which is shipped by Node.js by default.
4
8
5
-
**Important:** At the moment, Corepack only covers Yarn and pnpm. Given that we have little control on the npm project, we prefer to focus on the Yarn and pnpm use cases. As a result, Corepack doesn't have any effect at all on the way you use npm.
9
+
**Important:** At the moment, Corepack only covers Yarn and pnpm. Given that we
10
+
have little control on the npm project, we prefer to focus on the Yarn and pnpm
11
+
use cases. As a result, Corepack doesn't have any effect at all on the way you
12
+
use npm.
6
13
7
14
## How to Install
8
15
9
16
### Default Installs
10
17
11
-
Corepack is distributed by default with Node.js 14.19.0 and 16.9.0, but is opt-in for the time being. Run `corepack enable` to install the required shims.
18
+
Corepack is distributed by default with Node.js 14.19.0 and 16.9.0, but is
19
+
opt-in for the time being. Run `corepack enable` to install the required shims.
12
20
13
21
### Manual Installs
14
22
15
23
<details>
16
24
<summary>Click here to see how to install Corepack using npm</summary>
17
25
18
-
First uninstall your global Yarn and pnpm binaries (just leave npm). In general, you'd do this by running the following command:
26
+
First uninstall your global Yarn and pnpm binaries (just leave npm). In general,
27
+
you'd do this by running the following command:
19
28
20
29
```shell
21
30
npm uninstall -g yarn pnpm
@@ -30,21 +39,31 @@ Then install Corepack:
30
39
npm install -g corepack
31
40
```
32
41
33
-
We do acknowledge the irony and overhead of using npm to install Corepack, which is at least part of why the preferred option is to use the Corepack version that is distributed along with Node.js itself.
42
+
We do acknowledge the irony and overhead of using npm to install Corepack, which
43
+
is at least part of why the preferred option is to use the Corepack version that
44
+
is distributed along with Node.js itself.
34
45
35
46
</details>
36
47
37
48
## Usage
38
49
39
50
### When Building Packages
40
51
41
-
Just use your package managers as you usually would. Run `yarn install` in Yarn projects, `pnpm install` in pnpm projects, and `npm` in npm projects. Corepack will catch these calls, and depending on the situation:
52
+
Just use your package managers as you usually would. Run `yarn install` in Yarn
53
+
projects, `pnpm install` in pnpm projects, and `npm` in npm projects. Corepack
54
+
will catch these calls, and depending on the situation:
42
55
43
-
-**If the local project is configured for the package manager you're using**, Corepack will silently download and cache the latest compatible version.
56
+
-**If the local project is configured for the package manager you're using**,
57
+
Corepack will silently download and cache the latest compatible version.
44
58
45
-
-**If the local project is configured for a different package manager**, Corepack will request you to run the command again using the right package manager - thus avoiding corruptions of your install artifacts.
59
+
-**If the local project is configured for a different package manager**,
60
+
Corepack will request you to run the command again using the right package
61
+
manager - thus avoiding corruptions of your install artifacts.
46
62
47
-
-**If the local project isn't configured for any package manager**, Corepack will assume that you know what you're doing, and will use whatever package manager version has been pinned as "known good release". Check the relevant section for more details.
63
+
-**If the local project isn't configured for any package manager**, Corepack
64
+
will assume that you know what you're doing, and will use whatever package
65
+
manager version has been pinned as "known good release". Check the relevant
66
+
section for more details.
48
67
49
68
### When Authoring Packages
50
69
@@ -56,13 +75,18 @@ Set your package's manager with the `packageManager` field in `package.json`:
56
75
}
57
76
```
58
77
59
-
Here, `yarn` is the name of the package manager, specified at version `3.2.3`, along with the SHA-224 hash of this version for validation. `packageManager@x.y.z` is required. The hash is optional but strongly recommended as a security practice. Permitted values for the package manager are `yarn`, `npm`, and `pnpm`.
78
+
Here, `yarn` is the name of the package manager, specified at version `3.2.3`,
79
+
along with the SHA-224 hash of this version for validation.
80
+
`packageManager@x.y.z` is required. The hash is optional but strongly
81
+
recommended as a security practice. Permitted values for the package manager are
82
+
`yarn`, `npm`, and `pnpm`.
60
83
61
84
## Known Good Releases
62
85
63
86
When running Corepack within projects that don't list a supported package
64
87
manager, it will default to a set of Known Good Releases. In a way, you can
65
-
compare this to Node.js, where each version ships with a specific version of npm.
88
+
compare this to Node.js, where each version ships with a specific version of
89
+
npm.
66
90
67
91
If there is no Known Good Release for the requested package manager, Corepack
68
92
looks up the npm registry for the latest available version and cache it for
@@ -75,53 +99,76 @@ from the `corepack prepare` and `corepack hydrate` commands.
75
99
76
100
The utility commands detailed in the next section.
77
101
78
-
- Either you can use the network while building your container image, in which case you'll simply run `corepack prepare` to make sure that your image includes the Last Known Good release for the specified package manager.
102
+
- Either you can use the network while building your container image, in which
103
+
case you'll simply run `corepack prepare` to make sure that your image
104
+
includes the Last Known Good release for the specified package manager.
79
105
80
-
- If you want to have *all* Last Known Good releases for all package managers, just use the `--all` flag which will do just that.
106
+
- If you want to have _all_ Last Known Good releases for all package managers,
107
+
just use the `--all` flag which will do just that.
81
108
82
-
- Or you're publishing your project to a system where the network is unavailable, in which case you'll preemptively generate a package manager archive from your local computer (using `corepack prepare -o`) before storing it somewhere your container will be able to access (for example within your repository). After that it'll just be a matter of running `corepack hydrate <path/to/corepack.tgz>` to setup the cache.
109
+
- Or you're publishing your project to a system where the network is
110
+
unavailable, in which case you'll preemptively generate a package manager
111
+
archive from your local computer (using `corepack prepare -o`) before storing
112
+
it somewhere your container will be able to access (for example within your
113
+
repository). After that it'll just be a matter of running
114
+
`corepack hydrate <path/to/corepack.tgz>` to setup the cache.
This meta-command runs the specified package manager in the local folder. You can use it to force an install to run with a given version, which can be useful when looking for regressions.
120
+
This meta-command runs the specified package manager in the local folder. You
121
+
can use it to force an install to run with a given version, which can be useful
122
+
when looking for regressions.
89
123
90
-
Note that those commands still check whether the local project is configured for the given package manager (ie you won't be able to run `corepack yarn install` on a project where the `packageManager` field references `pnpm`).
124
+
Note that those commands still check whether the local project is configured for
125
+
the given package manager (ie you won't be able to run `corepack yarn install`
126
+
on a project where the `packageManager` field references `pnpm`).
|`--install-directory`| Add the shims to the specified location |
97
133
98
-
This command will detect where Node.js is installed and will create shims next to it for each of the specified package managers (or all of them if the command is called without parameters). Note that the npm shims will not be installed unless explicitly requested, as npm is currently distributed with Node.js through other means.
134
+
This command will detect where Node.js is installed and will create shims next
135
+
to it for each of the specified package managers (or all of them if the command
136
+
is called without parameters). Note that the npm shims will not be installed
137
+
unless explicitly requested, as npm is currently distributed with Node.js
|`--all`| Prepare the "Last Known Good" version of all supported package managers |
154
+
|`-o,--output`| Also generate an archive containing the package managers |
155
+
|`--activate`| Also update the "Last Known Good" release|
115
156
116
-
This command will download the given package managers (or the one configured for the local project if no argument is passed in parameter) and store it within the Corepack cache. If the `-o,--output` flag is set (optionally with a path as parameter), an archive will also be generated that can be used by the `corepack hydrate` command.
157
+
This command will download the given package managers (or the one configured for
158
+
the local project if no argument is passed in parameter) and store it within the
159
+
Corepack cache. If the `-o,--output` flag is set (optionally with a path as
160
+
parameter), an archive will also be generated that can be used by the
|`--activate`| Also update the "Last Known Good" release |
123
168
124
-
This command will retrieve the given package manager from the specified archive and will install it within the Corepack cache, ready to be used without further network interaction.
169
+
This command will retrieve the given package manager from the specified archive
170
+
and will install it within the Corepack cache, ready to be used without further
171
+
network interaction.
125
172
126
173
## Environment Variables
127
174
@@ -134,31 +181,41 @@ This command will retrieve the given package manager from the specified archive
134
181
manager versions that will be required for the projects you'll run, using
135
182
`corepack hydrate`).
136
183
137
-
-`COREPACK_ENABLE_STRICT` can be set to `0` to prevent Corepack from throwing error
138
-
if the package manager does not correspond to the one defined for the current project.
139
-
This means that if a user is using the package manager specified in the current project,
140
-
it will use the version specified by the project's `packageManager` field.
141
-
But if the user is using other package manager different from the one specified
142
-
for the current project, it will use the system-wide package manager version.
184
+
-`COREPACK_ENABLE_STRICT` can be set to `0` to prevent Corepack from throwing
185
+
error if the package manager does not correspond to the one defined for the
186
+
current project. This means that if a user is using the package manager
187
+
specified in the current project, it will use the version specified by the
188
+
project's `packageManager` field. But if the user is using other package
189
+
manager different from the one specified for the current project, it will use
190
+
the system-wide package manager version.
143
191
144
-
-`COREPACK_ENABLE_PROJECT_SPEC` can be set to `0` to prevent Corepack from checking
145
-
if the package manager corresponds to the one defined for the current project.
146
-
This means that it will always use the system-wide package manager regardless of
147
-
what is being specified in the project's `packageManager` field.
192
+
-`COREPACK_ENABLE_PROJECT_SPEC` can be set to `0` to prevent Corepack from
193
+
checking if the package manager corresponds to the one defined for the current
194
+
project. This means that it will always use the system-wide package manager
195
+
regardless of what is being specified in the project's `packageManager` field.
148
196
149
197
-`COREPACK_HOME` can be set in order to define where Corepack should install
150
198
the package managers. By default it is set to `%LOCALAPPDATA%\node\corepack`
151
199
on Windows, and to `$HOME/.cache/node/corepack` everywhere else.
152
200
153
-
-`COREPACK_ROOT` has no functional impact on Corepack itself; it's automatically being set in your environment by Corepack when it shells out to the underlying package managers, so that they can feature-detect its presence (useful for commands like `yarn init`).
201
+
-`COREPACK_ROOT` has no functional impact on Corepack itself; it's
202
+
automatically being set in your environment by Corepack when it shells out to
203
+
the underlying package managers, so that they can feature-detect its presence
204
+
(useful for commands like `yarn init`).
154
205
155
-
-`COREPACK_NPM_REGISTRY` sets the registry base url used when retrieving package managers from npm. Default value is `https://registry.npmjs.org`
206
+
-`COREPACK_NPM_REGISTRY` sets the registry base url used when retrieving
207
+
package managers from npm. Default value is `https://registry.npmjs.org`
156
208
157
-
-`COREPACK_NPM_TOKEN` sets a Bearer token authorization header when connecting to a npm type registry.
209
+
-`COREPACK_NPM_TOKEN` sets a Bearer token authorization header when connecting
210
+
to a npm type registry.
158
211
159
-
-`COREPACK_NPM_USERNAME` and `COREPACK_NPM_PASSWORD` to set a Basic authorization header when connecting to a npm type registry. Note that both environment variables are required and as plain text. If you want to send an empty password, explicitly set `COREPACK_NPM_PASSWORD` to an empty string.
212
+
-`COREPACK_NPM_USERNAME` and `COREPACK_NPM_PASSWORD` to set a Basic
213
+
authorization header when connecting to a npm type registry. Note that both
214
+
environment variables are required and as plain text. If you want to send an
215
+
empty password, explicitly set `COREPACK_NPM_PASSWORD` to an empty string.
160
216
161
-
-`HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` are supported through [`node-proxy-agent`](https://github.com/TooTallNate/node-proxy-agent).
217
+
-`HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` are supported through
0 commit comments