Docs menu

Package managers

npm, pnpm, and Yarn on Primcloud: how one is chosen, what each runs, private registries, and lockfiles.

On this page

Node.js apps can use npm, pnpm, or Yarn (classic or modern). An app with a Bun lockfile builds as a Bun app instead; see Bun package managers.

Which one runs#

The build uses the first of these it finds:

  1. A committed Yarn binary, named by yarnPath in .yarnrc.yml.
  2. The packageManager field in package.json, such as "[email protected]". It takes an exact version, not a range.
  3. engines.pnpm, a version range in package.json.
  4. engines.yarn, a version range in package.json.
  5. engines.npm, a version range in package.json.
  6. A yarn.lock, which selects Yarn.
  7. A pnpm-lock.yaml, which selects pnpm.
  8. The npm that comes with your Node.js version, when none of the above apply.

packageManager is the clearest way to choose:

package.json
{
  "packageManager": "[email protected]"
}

Or use a range:

package.json
{
  "engines": {
    "node": "24.x",
    "pnpm": "10.x"
  }
}

What each runs#

Each installs exactly what your lockfile lists:

Package manager Command Lockfile
npm npm ci package-lock.json
pnpm pnpm install --frozen-lockfile pnpm-lock.yaml
Yarn classic (v1) yarn install --frozen-lockfile yarn.lock
Yarn modern (v2+) yarn install --immutable yarn.lock

Your build scripts run afterward.

Lockfiles#

Commit the lockfile for the package manager you use. Without one, no dependencies are installed and your build scripts don't run.

Delete lockfiles from other package managers. With a yarn.lock beside your pnpm-lock.yaml and nothing in package.json naming a package manager, the build picks Yarn.

If package.json and the lockfile disagree, the install fails. Run the command from the table above locally to see the same error, then regenerate the lockfile (npm install, pnpm install, or yarn install) and commit it.

Private packages and registries#

Use your package manager's usual config files, with tokens read from secrets so they never enter the repo.

npm, pnpm, and Yarn classic read .npmrc at the repo root:

.npmrc
@my-org:registry=https://npm.pkg.example.com
//npm.pkg.example.com/:_authToken=${MY_ORG_NPM_TOKEN}

Then add MY_ORG_NPM_TOKEN as a secret. For GitHub Packages:

.npmrc
@my-org:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}

Yarn modern reads .yarnrc.yml:

.yarnrc.yml
npmScopes:
  my-org:
    npmRegistryServer: "https://npm.pkg.example.com"
    npmAuthToken: "${MY_ORG_NPM_TOKEN}"

Warning

Never commit tokens. Add them as secrets.