codekingpro/portable-devtools
115k
1# <img src="./icon.svg" height="25" /> corepack
2
3[](https://slack-invite.openjsf.org/)
4
5Corepack is a zero-runtime-dependency Node.js script that acts as a bridge
6between Node.js projects and the package managers they are intended to be used
7with during development. In practical terms, **Corepack lets you use Yarn, npm,
8and pnpm without having to install them**.
9
10## How to Install
11
12### Default Installs
13
14Corepack is distributed with Node.js from version 14.19.0 up to (but not including) 25.0.0.
15Run `corepack enable` to install the required Yarn and pnpm binaries on your path.
16
17### Manual Installs
18
19<details>
20<summary>Install Corepack using npm</summary>
21
22First uninstall your global Yarn and pnpm binaries (just leave npm). In general,
23you'd do this by running the following command:
24
25```shell
26npm uninstall -g yarn pnpm
27
28# That should be enough, but if you installed Yarn without going through npm it might
29# be more tedious - for example, you might need to run `brew uninstall yarn` as well.
30```
31
32Then install Corepack:
33
34```shell
35npm install -g corepack
36```
37
38We do acknowledge the irony and overhead of using npm to install Corepack, which
39is at least part of why the preferred option is to use the Corepack version that
40is distributed along with Node.js itself.
41
42</details>
43
44<details><summary>Update Corepack using npm</summary>
45
46To install the latest version of Corepack, use:
47
48```shell
49npm install -g corepack@latest
50```
51
52If Corepack was installed on your system using a Node.js Windows Installer
53`.msi` package then you might need to remove it before attempting to install a
54different version of Corepack using npm. You can select the Modify option of the
55Node.js app settings to access the Windows Installer feature selection, and on
56the "corepack manager" feature of the Node.js `.msi` package by selecting
57"Entire feature will be unavailable". See
58[Repair apps and programs in Windows](https://support.microsoft.com/en-us/windows/repair-apps-and-programs-in-windows-e90eefe4-d0a2-7c1b-dd59-949a9030f317)
59for instructions on accessing the Windows apps page to modify settings.
60
61</details>
62
63<details><summary>Install Corepack from source</summary>
64
65See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
66
67</details>
68
69## Usage
70
71### When Building Packages
72
73Just use your package managers as you usually would. Run `yarn install` in Yarn
74projects, `pnpm install` in pnpm projects, and `npm` in npm projects. Corepack
75will catch these calls, and depending on the situation:
76
77- **If the local project is configured for the package manager you're using**,
78 Corepack will download and cache the latest compatible version.
79
80- **If the local project is configured for a different package manager**,
81 Corepack will request you to run the command again using the right package
82 manager - thus avoiding corruptions of your install artifacts.
83
84- **If the local project isn't configured for any package manager**, Corepack
85 will assume that you know what you're doing, and will use whatever package
86 manager version has been pinned as "known good release". Check the relevant
87 section for more details.
88
89### When Authoring Packages
90
91Set your package's manager with the `packageManager` field in `package.json`:
92
93```json
94{
95 "packageManager": "yarn@3.2.3+sha224.953c8233f7a92884eee2de69a1b92d1f2ec1655e66d08071ba9a02fa"
96}
97```
98
99Here, `yarn` is the name of the package manager, specified at version `3.2.3`,
100along with the SHA-224 hash of this version for validation.
101`packageManager@x.y.z` is required. The hash is optional but strongly
102recommended as a security practice. Permitted values for the package manager are
103`yarn`, `npm`, and `pnpm`.
104
105You can also provide a URL to a `.js` file (which will be interpreted as a
106CommonJS module) or a `.tgz` file (which will be interpreted as a package, and
107the `"bin"` field of the `package.json` will be used to determine which file to
108use in the archive).
109
110```json
111{
112 "packageManager": "yarn@https://registry.npmjs.org/@yarnpkg/cli-dist/-/cli-dist-3.2.3.tgz#sha224.16a0797d1710d1fb7ec40ab5c3801b68370a612a9b66ba117ad9924b"
113}
114```
115
116#### `devEngines.packageManager`
117
118When a `devEngines.packageManager` field is defined, and is an object containing
119a `"name"` field (can also optionally contain `version` and `onFail` fields),
120Corepack will use it to validate you're using a compatible package manager.
121
122Depending on the value of `devEngines.packageManager.onFail`:
123
124- if set to `ignore`, Corepack won't print any warning or error.
125- if unset or set to `error`, Corepack will throw an error in case of a mismatch.
126- if set to `warn` or some other value, Corepack will print a warning in case
127 of mismatch.
128
129If the top-level `packageManager` field is missing, Corepack will use the
130package manager defined in `devEngines.packageManager` – in which case you must
131provide a specific version in `devEngines.packageManager.version`, ideally with
132a hash, as explained in the previous section:
133
134```json
135{
136 "devEngines":{
137 "packageManager": {
138 "name": "yarn",
139 "version": "3.2.3+sha224.953c8233f7a92884eee2de69a1b92d1f2ec1655e66d08071ba9a02fa"
140 }
141 }
142}
143```
144
145## Known Good Releases
146
147When running Corepack within projects that don't list a supported package
148manager, it will default to a set of Known Good Releases.
149
150If there is no Known Good Release for the requested package manager, Corepack
151looks up the npm registry for the latest available version and cache it for
152future use.
153
154The Known Good Releases can be updated system-wide using `corepack install -g`.
155When Corepack downloads a new version of a given package manager on the same
156major line as the Known Good Release, it auto-updates it by default.
157
158## Offline Workflow
159
160The utility commands detailed in the next section.
161
162- Either you can use the network while building your container image, in which
163 case you'll simply run `corepack pack` to make sure that your image
164 includes the Last Known Good release for the specified package manager.
165
166- Or you're publishing your project to a system where the network is
167 unavailable, in which case you'll preemptively generate a package manager
168 archive from your local computer (using `corepack pack -o`) before storing
169 it somewhere your container will be able to access (for example within your
170 repository). After that it'll just be a matter of running
171 `corepack install -g --cache-only <path/to/corepack.tgz>` to setup the cache.
172
173## Utility Commands
174
175### `corepack <binary name>[@<version>] [... args]`
176
177This meta-command runs the specified package manager in the local folder. You
178can use it to force an install to run with a given version, which can be useful
179when looking for regressions.
180
181Note that those commands still check whether the local project is configured for
182the given package manager (ie you won't be able to run `corepack yarn install`
183on a project where the `packageManager` field references `pnpm`).
184
185### `corepack cache clean`
186
187Clears the local `COREPACK_HOME` cache directory.
188
189### `corepack cache clear`
190
191Clears the local `COREPACK_HOME` cache directory.
192
193### `corepack enable [... name]`
194
195| Option | Description |
196| --------------------- | --------------------------------------- |
197| `--install-directory` | Add the shims to the specified location |
198
199This command will detect where Corepack is installed and will create shims next
200to it for each of the specified package managers (or all of them if the command
201is called without parameters). Note that the npm shims will not be installed
202unless explicitly requested, as npm is currently distributed with Node.js
203through other means.
204
205If the file system where the `corepack` binary is located is read-only, this
206command will fail. A workaround is to add the binaries as alias in your
207shell configuration file (e.g. in `~/.bash_aliases`):
208
209```sh
210alias yarn="corepack yarn"
211alias yarnpkg="corepack yarnpkg"
212alias pnpm="corepack pnpm"
213alias pnpx="corepack pnpx"
214alias npm="corepack npm"
215alias npx="corepack npx"
216```
217
218On Windows PowerShell, you can add functions using the `$PROFILE` automatic
219variable:
220
221```powershell
222echo 'function yarn { corepack yarn @args }' >> $PROFILE
223echo 'function yarnpkg { corepack yarnpkg @args }' >> $PROFILE
224echo 'function pnpm { corepack pnpm @args }' >> $PROFILE
225echo 'function pnpx { corepack pnpx @args }' >> $PROFILE
226echo 'function npm { corepack npm @args }' >> $PROFILE
227echo 'function npx { corepack npx @args }' >> $PROFILE
228```
229
230### `corepack disable [... name]`
231
232| Option | Description |
233| --------------------- | ------------------------------------------ |
234| `--install-directory` | Remove the shims to the specified location |
235
236This command will detect where Node.js is installed and will remove the shims
237from there.
238
239### `corepack install`
240
241Download and install the package manager configured in the local project.
242This command doesn't change the global version used when running the package
243manager from outside the project (use the \`-g,--global\` flag if you wish
244to do this).
245
246### `corepack install <-g,--global> [... name[@<version>]]`
247
248Install the selected package managers and install them on the system.
249
250Package managers thus installed will be configured as the new default when
251calling their respective binaries outside of projects defining the
252`packageManager` field.
253
254### `corepack pack [... name[@<version>]]`
255
256| Option | Description |
257| --------------------- | ------------------------------------------ |
258| `--json ` | Print the output folder rather than logs |
259| `-o,--output ` | Path where to generate the archive |
260
261Download the selected package managers and store them inside a tarball
262suitable for use with `corepack install -g`.
263
264### `corepack use <name[@<version>]>`
265
266When run, this command will retrieve the latest release matching the provided
267descriptor, assign it to the project's package.json file, and automatically
268perform an install.
269
270### `corepack up`
271
272Retrieve the latest available version for the current major release line of
273the package manager used in the local project, and update the project to use
274it.
275
276Unlike `corepack use` this command doesn't take a package manager name nor a
277version range, as it will always select the latest available version from the
278range specified in `devEngines.packageManager.version`, or fallback to the
279same major line. Should you need to upgrade to a new major, use an explicit
280`corepack use {name}@latest` call (or simply `corepack use {name}`).
281
282## Environment Variables
283
284- `COREPACK_DEFAULT_TO_LATEST` can be set to `0` in order to instruct Corepack
285 not to lookup on the remote registry for the latest version of the selected
286 package manager, and to not update the Last Known Good version when it
287 downloads a new version of the same major line.
288
289- `COREPACK_ENABLE_AUTO_PIN` can be set to `1` to instruct Corepack to
290 update the `packageManager` field when it detects that the local package
291 doesn't list it. In general we recommend to always list a `packageManager`
292 field (which you can easily set through `corepack use [name]@[version]`), as
293 it ensures that your project installs are always deterministic.
294
295- `COREPACK_ENABLE_DOWNLOAD_PROMPT` can be set to `0` to
296 prevent Corepack showing the URL when it needs to download software, or can be
297 set to `1` to have the URL shown. By default, when Corepack is called
298 explicitly (e.g. `corepack pnpm …`), it is set to `0`; when Corepack is called
299 implicitly (e.g. `pnpm …`), it is set to `1`.
300 The default value cannot be overridden in a `.corepack.env` file.
301 When standard input is a TTY and no CI environment is detected, Corepack will
302 ask for user input before starting the download.
303
304- `COREPACK_ENABLE_UNSAFE_CUSTOM_URLS` can be set to `1` to allow use of
305 custom URLs to load a package manager known by Corepack (`yarn`, `npm`, and
306 `pnpm`).
307
308- `COREPACK_ENABLE_NETWORK` can be set to `0` to prevent Corepack from accessing
309 the network (in which case you'll be responsible for hydrating the package
310 manager versions that will be required for the projects you'll run, using
311 `corepack install -g --cache-only`).
312
313- `COREPACK_ENABLE_STRICT` can be set to `0` to prevent Corepack from throwing
314 error if the package manager does not correspond to the one defined for the
315 current project. This means that if a user is using the package manager
316 specified in the current project, it will use the version specified by the
317 project's `packageManager` field. But if the user is using other package
318 manager different from the one specified for the current project, it will use
319 the system-wide package manager version.
320
321- `COREPACK_ENABLE_PROJECT_SPEC` can be set to `0` to prevent Corepack from
322 checking if the package manager corresponds to the one defined for the current
323 project. This means that it will always use the system-wide package manager
324 regardless of what is being specified in the project's `packageManager` field.
325
326- `COREPACK_ENV_FILE` can be set to `0` to request Corepack to not attempt to
327 load `.corepack.env`; it can be set to a path to specify a different env file.
328 Only keys that start with `COREPACK_` and are not in the exception list
329 (`COREPACK_ENABLE_DOWNLOAD_PROMPT` and `COREPACK_ENV_FILE` are ignored)
330 will be taken into account.
331 For Node.js 18.x users, this setting has no effect as that version doesn't
332 support parsing of `.env` files.
333
334- `COREPACK_HOME` can be set in order to define where Corepack should install
335 the package managers. By default it is set to `%LOCALAPPDATA%\node\corepack`
336 on Windows, and to `$HOME/.cache/node/corepack` everywhere else.
337
338- `COREPACK_ROOT` has no functional impact on Corepack itself; it's
339 automatically being set in your environment by Corepack when it shells out to
340 the underlying package managers, so that they can feature-detect its presence
341 (useful for commands like `yarn init`).
342
343- `COREPACK_NPM_REGISTRY` sets the registry base url used when retrieving
344 package managers from npm. Default value is `https://registry.npmjs.org`
345
346- `COREPACK_NPM_TOKEN` sets a Bearer token authorization header when connecting
347 to a npm type registry.
348
349- `COREPACK_NPM_USERNAME` and `COREPACK_NPM_PASSWORD` to set a Basic
350 authorization header when connecting to a npm type registry. Note that both
351 environment variables are required and as plain text. If you want to send an
352 empty password, explicitly set `COREPACK_NPM_PASSWORD` to an empty string.
353
354- `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` are supported through
355 [`proxy-from-env`](https://github.com/Rob--W/proxy-from-env).
356
357- `COREPACK_INTEGRITY_KEYS` can be set to an empty string or `0` to
358 instruct Corepack to skip integrity checks, or to a JSON string containing
359 custom keys.
360
361## Troubleshooting
362
363The environment variable `DEBUG` can be set to `corepack` to enable additional debug logging.
364
365### Networking
366
367There are a wide variety of networking issues that can occur while running
368`corepack` commands. Things to check:
369
370- Make sure your network connection is active.
371- Make sure the host for your request can be resolved by your DNS; try using
372 `curl [URL]` (ipv4) and `curl -6 [URL]` (ipv6) from your shell.
373- Check your proxy settings (see [Environment Variables](#environment-variables)).
374
375## Contributing
376
377See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
378
379## License (MIT)
380
381See [`LICENSE.md`](./LICENSE.md).
382