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 84## Known Good Releases 85 86When running Corepack within projects that don't list a supported package 87manager, it will default to a set of Known Good Releases. In a way, you can 88compare this to Node.js, where each version ships with a specific version of 89npm. 90 91If there is no Known Good Release for the requested package manager, Corepack 92looks up the npm registry for the latest available version and cache it for 93future use. 94 95The Known Good Releases can be updated system-wide using the `--activate` flag 96from the `corepack prepare` and `corepack hydrate` commands. 97 98## Offline Workflow 99 100The utility commands detailed in the next section. 101 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. 105 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. 108 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. 115 116## Utility Commands 117 118### `corepack <binary name>[@<version>] [... args]` 119 120This meta-command runs the specified package manager in the local folder. You 121can use it to force an install to run with a given version, which can be useful 122when looking for regressions. 123 124Note that those commands still check whether the local project is configured for 125the given package manager (ie you won't be able to run `corepack yarn install` 126on a project where the `packageManager` field references `pnpm`). 127 128### `corepack enable [... name]` 129 130| Option | Description | 131| --------------------- | --------------------------------------- | 132| `--install-directory` | Add the shims to the specified location | 133 134This command will detect where Corepack is installed and will create shims next 135to it for each of the specified package managers (or all of them if the command 136is called without parameters). Note that the npm shims will not be installed 137unless explicitly requested, as npm is currently distributed with Node.js 138through other means. 139 140If the file system where the `corepack` binary is located is read-only, this 141command will fail. A workaround is to add the binaries as alias in your 142shell configuration file (e.g. in `~/.bash_aliases`): 143 144```sh 145alias yarn="corepack yarn" 146alias yarnpkg="corepack yarnpkg" 147alias pnpm="corepack pnpm" 148alias pnpx="corepack pnpx" 149alias npm="corepack npm" 150alias npx="corepack npx" 151``` 152 153On Windows PowerShell, you can add functions using the `$PROFILE` automatic 154variable: 155 156```powershell 157echo "function yarn { corepack yarn `$args }" >> $PROFILE 158echo "function yarnpkg { corepack yarnpkg `$args }" >> $PROFILE 159echo "function pnpm { corepack pnpm `$args }" >> $PROFILE 160echo "function pnpx { corepack pnpx `$args }" >> $PROFILE 161echo "function npm { corepack npm `$args }" >> $PROFILE 162echo "function npx { corepack npx `$args }" >> $PROFILE 163``` 164 165### `corepack disable [... name]` 166 167| Option | Description | 168| --------------------- | ------------------------------------------ | 169| `--install-directory` | Remove the shims to the specified location | 170 171This command will detect where Node.js is installed and will remove the shims 172from there. 173 174### `corepack prepare [... name@version]` 175 176| Option | Description | 177| ------------- | ----------------------------------------------------------------------- | 178| `--all` | Prepare the "Last Known Good" version of all supported package managers | 179| `-o,--output` | Also generate an archive containing the package managers | 180| `--activate` | Also update the "Last Known Good" release | 181 182This command will download the given package managers (or the one configured for 183the local project if no argument is passed in parameter) and store it within the 184Corepack cache. If the `-o,--output` flag is set (optionally with a path as 185parameter), an archive will also be generated that can be used by the 186`corepack hydrate` command. 187 188### `corepack hydrate <path/to/corepack.tgz>` 189 190| Option | Description | 191| ------------ | ----------------------------------------- | 192| `--activate` | Also update the "Last Known Good" release | 193 194This command will retrieve the given package manager from the specified archive 195and will install it within the Corepack cache, ready to be used without further 196network interaction. 197 198## Environment Variables 199 200- `COREPACK_DEFAULT_TO_LATEST` can be set to `0` in order to instruct Corepack 201 not to lookup on the remote registry for the latest version of the selected 202 package manager. 203 204- `COREPACK_ENABLE_NETWORK` can be set to `0` to prevent Corepack from accessing 205 the network (in which case you'll be responsible for hydrating the package 206 manager versions that will be required for the projects you'll run, using 207 `corepack hydrate`). 208 209- `COREPACK_ENABLE_STRICT` can be set to `0` to prevent Corepack from throwing 210 error if the package manager does not correspond to the one defined for the 211 current project. This means that if a user is using the package manager 212 specified in the current project, it will use the version specified by the 213 project's `packageManager` field. But if the user is using other package 214 manager different from the one specified for the current project, it will use 215 the system-wide package manager version. 216 217- `COREPACK_ENABLE_PROJECT_SPEC` can be set to `0` to prevent Corepack from 218 checking if the package manager corresponds to the one defined for the current 219 project. This means that it will always use the system-wide package manager 220 regardless of what is being specified in the project's `packageManager` field. 221 222- `COREPACK_HOME` can be set in order to define where Corepack should install 223 the package managers. By default it is set to `%LOCALAPPDATA%\node\corepack` 224 on Windows, and to `$HOME/.cache/node/corepack` everywhere else. 225 226- `COREPACK_ROOT` has no functional impact on Corepack itself; it's 227 automatically being set in your environment by Corepack when it shells out to 228 the underlying package managers, so that they can feature-detect its presence 229 (useful for commands like `yarn init`). 230 231- `COREPACK_NPM_REGISTRY` sets the registry base url used when retrieving 232 package managers from npm. Default value is `https://registry.npmjs.org` 233 234- `COREPACK_NPM_TOKEN` sets a Bearer token authorization header when connecting 235 to a npm type registry. 236 237- `COREPACK_NPM_USERNAME` and `COREPACK_NPM_PASSWORD` to set a Basic 238 authorization header when connecting to a npm type registry. Note that both 239 environment variables are required and as plain text. If you want to send an 240 empty password, explicitly set `COREPACK_NPM_PASSWORD` to an empty string. 241 242- `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` are supported through 243 [`node-proxy-agent`](https://github.com/TooTallNate/node-proxy-agent). 244 245## Troubleshooting 246 247### Networking 248 249There are a wide variety of networking issues that can occur while running `corepack` commands. Things to check: 250 251- Make sure your network connection is active. 252- Make sure the host for your request can be resolved by your DNS; try using 253 `curl [URL]` (ipv4) and `curl -6 [URL]` (ipv6) from your shell. 254- Check your proxy settings (see [Environment Variables](#environment-variables)). 255 256## Contributing 257 258See [`CONTRIBUTING.md`](./CONTRIBUTING.md). 259 260## Design 261 262See [`DESIGN.md`](/DESIGN.md). 263 264## License (MIT) 265 266See [`LICENSE.md`](./LICENSE.md). 267
