1# <img src="./icon.svg" height="25" /> corepack 2 3Corepack is a zero-runtime-dependency Node.js script that acts as a bridge 4between Node.js projects and the package managers they are intended to be used 5with during development. In practical terms, **Corepack lets you use Yarn, npm, 6and pnpm without having to install them**. 7 8## How to Install 9 10### Default Installs 11 12Corepack is [distributed by default with all recent Node.js versions](https://nodejs.org/api/corepack.html). 13Run `corepack enable` to install the required Yarn and pnpm binaries on your path. 14 15### Manual Installs 16 17<details> 18<summary>Install Corepack using npm</summary> 19 20First uninstall your global Yarn and pnpm binaries (just leave npm). In general, 21you'd do this by running the following command: 22 23```shell 24npm uninstall -g yarn pnpm 25 26# That should be enough, but if you installed Yarn without going through npm it might 27# be more tedious - for example, you might need to run `brew uninstall yarn` as well. 28``` 29 30Then install Corepack: 31 32```shell 33npm install -g corepack 34``` 35 36We do acknowledge the irony and overhead of using npm to install Corepack, which 37is at least part of why the preferred option is to use the Corepack version that 38is distributed along with Node.js itself. 39 40</details> 41 42<details><summary>Install Corepack from source</summary> 43 44See [`CONTRIBUTING.md`](./CONTRIBUTING.md). 45 46</details> 47 48## Usage 49 50### When Building Packages 51 52Just use your package managers as you usually would. Run `yarn install` in Yarn 53projects, `pnpm install` in pnpm projects, and `npm` in npm projects. Corepack 54will catch these calls, and depending on the situation: 55 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. 58 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. 62 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. 67 68### When Authoring Packages 69 70Set your package's manager with the `packageManager` field in `package.json`: 71 72```json 73{ 74 "packageManager": "yarn@3.2.3+sha224.953c8233f7a92884eee2de69a1b92d1f2ec1655e66d08071ba9a02fa" 75} 76``` 77 78Here, `yarn` is the name of the package manager, specified at version `3.2.3`, 79along with the SHA-224 hash of this version for validation. 80`packageManager@x.y.z` is required. The hash is optional but strongly 81recommended as a security practice. Permitted values for the package manager are 82`yarn`, `npm`, and `pnpm`. 83 84You can also provide a URL to a `.js` file (which will be interpreted as a 85CommonJS module) or a `.tgz` file (which will be interpreted as a package, and 86the `"bin"` field of the `package.json` will be used to determine which file to 87use in the archive). 88 89```json 90{ 91 "packageManager": "yarn@https://registry.npmjs.org/@yarnpkg/cli-dist/-/cli-dist-3.2.3.tgz#sha224.16a0797d1710d1fb7ec40ab5c3801b68370a612a9b66ba117ad9924b" 92} 93``` 94 95## Known Good Releases 96 97When running Corepack within projects that don't list a supported package 98manager, it will default to a set of Known Good Releases. 99 100If there is no Known Good Release for the requested package manager, Corepack 101looks up the npm registry for the latest available version and cache it for 102future use. 103 104The Known Good Releases can be updated system-wide using `corepack install -g`. 105When Corepack downloads a new version of a given package manager on the same 106major line as the Known Good Release, it auto-updates it by default. 107 108## Offline Workflow 109 110The utility commands detailed in the next section. 111 112- Either you can use the network while building your container image, in which 113 case you'll simply run `corepack pack` to make sure that your image 114 includes the Last Known Good release for the specified package manager. 115 116- Or you're publishing your project to a system where the network is 117 unavailable, in which case you'll preemptively generate a package manager 118 archive from your local computer (using `corepack pack -o`) before storing 119 it somewhere your container will be able to access (for example within your 120 repository). After that it'll just be a matter of running 121 `corepack install -g --cache-only <path/to/corepack.tgz>` to setup the cache. 122 123## Utility Commands 124 125### `corepack <binary name>[@<version>] [... args]` 126 127This meta-command runs the specified package manager in the local folder. You 128can use it to force an install to run with a given version, which can be useful 129when looking for regressions. 130 131Note that those commands still check whether the local project is configured for 132the given package manager (ie you won't be able to run `corepack yarn install` 133on a project where the `packageManager` field references `pnpm`). 134 135### `corepack cache clean` 136 137Clears the local `COREPACK_HOME` cache directory. 138 139### `corepack cache clear` 140 141Clears the local `COREPACK_HOME` cache directory. 142 143### `corepack enable [... name]` 144 145| Option | Description | 146| --------------------- | --------------------------------------- | 147| `--install-directory` | Add the shims to the specified location | 148 149This command will detect where Corepack is installed and will create shims next 150to it for each of the specified package managers (or all of them if the command 151is called without parameters). Note that the npm shims will not be installed 152unless explicitly requested, as npm is currently distributed with Node.js 153through other means. 154 155If the file system where the `corepack` binary is located is read-only, this 156command will fail. A workaround is to add the binaries as alias in your 157shell configuration file (e.g. in `~/.bash_aliases`): 158 159```sh 160alias yarn="corepack yarn" 161alias yarnpkg="corepack yarnpkg" 162alias pnpm="corepack pnpm" 163alias pnpx="corepack pnpx" 164alias npm="corepack npm" 165alias npx="corepack npx" 166``` 167 168On Windows PowerShell, you can add functions using the `$PROFILE` automatic 169variable: 170 171```powershell 172echo "function yarn { corepack yarn `$args }" >> $PROFILE 173echo "function yarnpkg { corepack yarnpkg `$args }" >> $PROFILE 174echo "function pnpm { corepack pnpm `$args }" >> $PROFILE 175echo "function pnpx { corepack pnpx `$args }" >> $PROFILE 176echo "function npm { corepack npm `$args }" >> $PROFILE 177echo "function npx { corepack npx `$args }" >> $PROFILE 178``` 179 180### `corepack disable [... name]` 181 182| Option | Description | 183| --------------------- | ------------------------------------------ | 184| `--install-directory` | Remove the shims to the specified location | 185 186This command will detect where Node.js is installed and will remove the shims 187from there. 188 189### `corepack install` 190 191Download and install the package manager configured in the local project. 192This command doesn't change the global version used when running the package 193manager from outside the project (use the \`-g,--global\` flag if you wish 194to do this). 195 196### `corepack install <-g,--global> [... name[@<version>]]` 197 198Install the selected package managers and install them on the system. 199 200Package managers thus installed will be configured as the new default when 201calling their respective binaries outside of projects defining the 202`packageManager` field. 203 204### `corepack pack [... name[@<version>]]` 205 206| Option | Description | 207| --------------------- | ------------------------------------------ | 208| `--json ` | Print the output folder rather than logs | 209| `-o,--output ` | Path where to generate the archive | 210 211Download the selected package managers and store them inside a tarball 212suitable for use with `corepack install -g`. 213 214### `corepack use <name[@<version>]>` 215 216When run, this command will retrieve the latest release matching the provided 217descriptor, assign it to the project's package.json file, and automatically 218perform an install. 219 220### `corepack up` 221 222Retrieve the latest available version for the current major release line of 223the package manager used in the local project, and update the project to use 224it. 225 226Unlike `corepack use` this command doesn't take a package manager name nor a 227version range, as it will always select the latest available version from the 228same major line. Should you need to upgrade to a new major, use an explicit 229`corepack use {name}@latest` call (or simply `corepack use {name}`). 230 231## Environment Variables 232 233- `COREPACK_DEFAULT_TO_LATEST` can be set to `0` in order to instruct Corepack 234 not to lookup on the remote registry for the latest version of the selected 235 package manager, and to not update the Last Known Good version when it 236 downloads a new version of the same major line. 237 238- `COREPACK_ENABLE_DOWNLOAD_PROMPT` can be set to `0` to 239 prevent Corepack showing the URL when it needs to download software, or can be 240 set to `1` to have the URL shown. By default, when Corepack is called 241 explicitly (e.g. `corepack pnpm …`), it is set to `0`; when Corepack is called 242 implicitely (e.g. `pnpm …`), it is set to `1`. 243 When standard input is a TTY and no CI environment is detected, Corepack will 244 ask for user input before starting the download. 245 246- `COREPACK_ENABLE_UNSAFE_CUSTOM_URLS` can be set to `1` to allow use of 247 custom URLs to load a package manager known by Corepack (`yarn`, `npm`, and 248 `pnpm`). 249 250- `COREPACK_ENABLE_NETWORK` can be set to `0` to prevent Corepack from accessing 251 the network (in which case you'll be responsible for hydrating the package 252 manager versions that will be required for the projects you'll run, using 253 `corepack install -g --cache-only`). 254 255- `COREPACK_ENABLE_STRICT` can be set to `0` to prevent Corepack from throwing 256 error if the package manager does not correspond to the one defined for the 257 current project. This means that if a user is using the package manager 258 specified in the current project, it will use the version specified by the 259 project's `packageManager` field. But if the user is using other package 260 manager different from the one specified for the current project, it will use 261 the system-wide package manager version. 262 263- `COREPACK_ENABLE_PROJECT_SPEC` can be set to `0` to prevent Corepack from 264 checking if the package manager corresponds to the one defined for the current 265 project. This means that it will always use the system-wide package manager 266 regardless of what is being specified in the project's `packageManager` field. 267 268- `COREPACK_HOME` can be set in order to define where Corepack should install 269 the package managers. By default it is set to `%LOCALAPPDATA%\node\corepack` 270 on Windows, and to `$HOME/.cache/node/corepack` everywhere else. 271 272- `COREPACK_ROOT` has no functional impact on Corepack itself; it's 273 automatically being set in your environment by Corepack when it shells out to 274 the underlying package managers, so that they can feature-detect its presence 275 (useful for commands like `yarn init`). 276 277- `COREPACK_NPM_REGISTRY` sets the registry base url used when retrieving 278 package managers from npm. Default value is `https://registry.npmjs.org` 279 280- `COREPACK_NPM_TOKEN` sets a Bearer token authorization header when connecting 281 to a npm type registry. 282 283- `COREPACK_NPM_USERNAME` and `COREPACK_NPM_PASSWORD` to set a Basic 284 authorization header when connecting to a npm type registry. Note that both 285 environment variables are required and as plain text. If you want to send an 286 empty password, explicitly set `COREPACK_NPM_PASSWORD` to an empty string. 287 288- `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` are supported through 289 [`node-proxy-agent`](https://github.com/TooTallNate/node-proxy-agent). 290 291## Troubleshooting 292 293### Networking 294 295There are a wide variety of networking issues that can occur while running `corepack` commands. Things to check: 296 297- Make sure your network connection is active. 298- Make sure the host for your request can be resolved by your DNS; try using 299 `curl [URL]` (ipv4) and `curl -6 [URL]` (ipv6) from your shell. 300- Check your proxy settings (see [Environment Variables](#environment-variables)). 301 302## Contributing 303 304See [`CONTRIBUTING.md`](./CONTRIBUTING.md). 305 306## Design 307 308See [`DESIGN.md`](/DESIGN.md). 309 310## License (MIT) 311 312See [`LICENSE.md`](./LICENSE.md). 313
