Corepack is an experimental tool that helps you to manage your package managers. It ships with Node.js core so you probably have it installed already.
Why do I need Corepack?
There are many different package managers for Node.js, the most notable being npm, yarn, and pnpm. Each has a similar feature set with different trade offs. They all do the following:
- Add/remove/update/dedupe dependencies
- Run package.json scripts
- Manage monorepos (via workspaces)
- Reproducible installs (via lockfile)
While these features seem similar, they have different implementations. Specifically, "reproducible installs" is only guaranteed when you use the same package manager that knows how to read a given lockfile, such as:
- package-lock.json
- yarn.lock
- pnpm-lock.yaml
Not to mention, lockfiles might change implementations between different versions of a package manager. For example, v2 lockfiles introduced in npm 7 are not compatible with earlier versions of npm.
Ok we established the package manager version is important, but how can we keep that version in sync?
Before Corepack, it was something manual like:
npm install --global pnpm@7.9.0
Using npm to install pnpm, is the equivalent of using Internet Explorer to install Chrome.
What is Corepack?
Corepack is an experimental tool that helps you to manage your package managers. Although you may have never heard of it, Corepack ships with Node.js 14.19.0 and newer. So you likely have it installed already!
Corepack transparently installs the correct package manager version based on the closest package.json file. For example, you can configure pnpm 6 with one project and pnpm 7 with another project, no need to run additional commands.
How do I use Corepack?
To get started, make sure you are using Node.js 14.19.0 or newer.
Then, update your project's package.json file with a packageManager property. This must be the exact version of the package manager.
{
"packageManager": "pnpm@7.9.0
}
Finally, run corepack enable pnpm once per machine to install a shim.
Now every time you run pnpm, the correct version will be selected. If that version has never been installed on the current machine, Corepack will install it transparently in the background before executing.
If you want to see if Corepack is using a cached version or installing from the network, set DEBUG=corepack environment variable to see verbose logs.
If no package.json is found, Corepack will use the global version. You can update the global version by running the following:
corepack prepare pnpm@7.9.0 --activate
Who is Corepack for?
Everyone can benefit from Corepack, especially projects with multiple developers.
Corepack ensures that you, your collaborators, your CI, your deployment platform all use the same version of the same package manager.
When will Corepack become stable?
Corepack is considered experimental status but there is a discussion about going stable in the future.
The biggest caveat I've found today is that Corepack can sometimes be too strict and cause Usage Error: This project is configured to use pkgmgr.