repository·main·Indexed 25 days ago
https://github.com/nodejs/corepackCorepack is a zero-runtime-dependency Node.js script that acts as a bridge between Node.js projects and package managers such as Yarn, npm, and pnpm. It enables developers to use specific package manager versions without manual installation by utilizing the packageManager field in package.json. Corepack provides CLI commands for enabling shims, managing versions via corepack use and corepack up, and supporting offline workflows through the corepack pack and corepack install commands.
Corepack is distributed with Node.js (versions 14.19.0 up to 25.0.0). To install the required Yarn and pnpm binaries on your path, run corepack enable.
If you need to install Corepack manually via npm (e.g., if it wasn't bundled with your Node.js installation), first uninstall any existing global Yarn and pnpm binaries to avoid conflicts, then install Corepack globally.
To use Corepack in environments without network access (like certain container builds), follow these steps:
corepack pack -o <path>..tgz file to your offline environment/repository.corepack install -g --cache-only <path/to/corepack.tgz>.You can use the devEngines.packageManager field to validate that developers are using a compatible package manager. This is useful when you want to warn or error if the version doesn't match, without strictly pinning the packageManager field.
Supported fields within the object:
name: The package manager name.version: The required version (ideally with a hash).onFail: Defines behavior on mismatch:ignore: No warning or error.error (default): Throws an error.warn: Prints a warning.{
"devEngines":{
"packageManager": {
"name": "yarn",
"version": "3.2.3+sha224.953c8233f7a92884eee2de69a1b92d1f2ec1655e66d08071ba9a02fa",
"onFail": "warn"
}
}
}To ensure all contributors use the same package manager and version, define the packageManager field in your package.json. This field accepts the package manager name, version, and an optional SHA hash for security validation.
Permitted values: yarn, npm, and pnpm.
{
"packageManager": "yarn@3.2.3+sha224.953c8233f7a92884eee2de69a1b92d1f2ec1655e66d08071ba9a02fa"
}DEBUG environment variable to corepack.If you encounter networking errors while running Corepack commands, verify the following:
curl [URL] (for ipv4) or curl -6 [URL] (for ipv6) in your shell.HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables).COREPACK_ENABLE_DOWNLOAD_PROMPT:0: Prevents showing the download URL.1: Shows the download URL.corepack pnpm ...), it defaults to 0. When called implicitly (e.g., pnpm ...), it defaults to 1. This cannot be overridden in a .corepack.env file.COREPACK_INTEGRITY_KEYS: Set to an empty string or 0 to skip integrity checks. Alternatively, provide a JSON string containing custom keys.corepack enable command creates shims for package managers. If the filesystem is read-only, you should use shell aliases instead.Corepack can be configured using several environment variables to control behavior regarding package manager lookups, security, networking, and storage.
COREPACK_DEFAULT_TO_LATEST: Set to 0 to prevent Corepack from looking up the latest version on the remote registry and to prevent updating the 'Last Known Good' version when downloading a new version of the same major line.COREPACK_ENABLE_AUTO_PIN: Set to 1 to instruct Corepack to update the packageManager field in your project when it detects the local version doesn't match.COREPACK_ENABLE_STRICT: Set to 0 to prevent Corepack from throwing an error if the package manager used does not match the one defined in the project's packageManager field. In this mode, if the user uses a different package manager than specified, it falls back to the system-wide version.COREPACK_ENABLE_PROJECT_SPEC: Set to 0 to prevent Corepack from checking the packageManager field entirely, forcing the use of the system-wide package manager.COREPACK_ENABLE_NETWORK: Set to 0 to disable network access. In this mode, you must manually hydrate required package managers using corepack install -g --cache-only.COREPACK_NPM_REGISTRY: Sets the registry base URL for retrieving package managers (default: https://registry.npmjs.org).COREPACK_NPM_TOKEN: Sets a Bearer token for npm-type registries.COREPACK_NPM_USERNAME and COREPACK_NPM_PASSWORD: Sets Basic authorization headers. Both are required as plain text.COREPACK_ENABLE_UNSAFE_CUSTOM_URLS: Set to 1 to allow custom URLs for loading yarn, npm, or pnpm.HTTP_PROXY, HTTPS_PROXY, NO_PROXY) are supported via NODE_USE_ENV_PROXY=1.COREPACK_HOME: Defines where package managers are installed. Defaults to %LOCALAPPDATA%\node\corepack on Windows and $HOME/.cache/node/corepack elsewhere.COREPACK_ENV_FILE: Specify a path to a custom environment file, or set to 0 to disable loading .corepack.env.corepack pack command is used to download package managers into a tarball, which is useful for offline workflows or container images.Use these commands to manage and update the package manager version defined in your project:
corepack use <name[@<version>]>: Retrieves the specified version, updates your package.json with the new packageManager field, and automatically performs an install.corepack up: Updates the project to the latest available version within the current major release line of the package manager used in the local project.