Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 37 ยท Build Settings and Environments

Node Versions and Package Managers

Pin the Node.js version and choose npm, yarn, pnpm or bun for builds on Vercel and Netlify. Fix works-on-my-machine failures with .nvmrc, engines, lockfiles and corepack.

The most common reason a build passes on your laptop and fails online is a different Node.js version. Your machine may run a new release while the platform defaults to another. Pinning the version, and the package manager, makes builds repeatable and removes a whole class of mystery failures.

Pin the Node version

You can state the version in several places. Pick one and keep it consistent with your local setup.

Method How Vercel Netlify
.nvmrc file A file containing 22 or 22.11.0 Not read by default (use the other options) Read automatically
engines in package.json "engines": { "node": "22.x" } Read Read in newer setups; check docs
Dashboard setting Node.js Version dropdown Yes (Project Settings > General) Via NODE_VERSION variable
Environment variable NODE_VERSION=22 No (use setting or engines) Yes
netlify.toml [build.environment] NODE_VERSION = "22" n/a Yes

Support differs between platforms and changes over time, so treat this table as a guide and confirm in the build log, which prints the Node version used. A reliable pattern that works on both:

JSON
{
  "engines": { "node": ">=22 <23" }
}

plus, for Netlify, a .nvmrc:

TEXT
22

Use an active LTS (long-term support) version for production. Odd-numbered releases are short-lived and not meant for production use.

Node.js Does this Node satisfy the range? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Choosing the package manager

Both platforms look at your lockfile to decide which tool to run:

Lockfile Install runs
package-lock.json npm install or npm ci
yarn.lock yarn install
pnpm-lock.yaml pnpm install
bun.lockb or bun.lock bun install

If you commit more than one lockfile the platform may pick the wrong one, so keep exactly one. To pin the tool version itself, use the packageManager field in package.json, which corepack (bundled with Node) understands:

JSON
{
  "packageManager": "[email protected]"
}

Both platforms support corepack: on Vercel enable it with the environment variable ENABLE_EXPERIMENTAL_COREPACK=1, and on Netlify it is honored for the packageManager field in recent build images. Verify in the log which version ran.

Node.js Which install command would run? (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Lockfiles are not optional

Without a lockfile, the platform resolves dependency versions fresh on every build, so a package released overnight can break your deploy while your code did not change. Commit the lockfile and prefer commands that install exactly from it (npm ci, pnpm install --frozen-lockfile, yarn install --immutable). When the lockfile and package.json disagree, a frozen install fails loudly, which is what you want in CI.

Install problems and quick fixes

  • ERESOLVE peer dependency errors. The lockfile is out of date or versions truly conflict. Fix the versions locally, regenerate the lockfile and commit. Avoid blindly using --legacy-peer-deps unless you understand the trade-off.
  • Private packages. Authenticate with a token in an environment variable referenced from .npmrc (for example //registry.example.com/:_authToken=${NPM_TOKEN}); never commit the token itself.
  • Native modules failing to build. The build machine is Linux; packages with native code need a compatible Node version and sometimes extra system libraries. Prefer packages with prebuilt binaries.
  • Out of memory. Large installs or builds can exceed the memory limit. Reduce parallelism or split the project.

Match local and remote

Use a version manager locally (nvm, fnm, Volta, or mise) and keep .nvmrc or engines in sync. A short checklist before pushing:

  1. node -v equals the version in .nvmrc.
  2. One lockfile is committed.
  3. npm ci && npm run build succeeds from a clean checkout.
Node.js Environment parity report (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the most common cause of a build passing locally but failing on the platform?

    Environment differences such as the Node version are the usual culprit.
  2. 2. How does the platform decide whether to run npm, yarn or pnpm?

    The presence of package-lock.json, yarn.lock or pnpm-lock.yaml selects the tool.
  3. 3. What does the packageManager field in package.json do with corepack?

    Corepack reads it and uses exactly that package manager version.
  4. 4. Why prefer npm ci in builds?

    Frozen installs make builds reproducible.

Summary

  • Pin Node with engines, .nvmrc, a dashboard setting or NODE_VERSION, and check the build log.
  • Use an active LTS version for production.
  • Commit exactly one lockfile; it also selects the package manager.
  • Pin the manager version with packageManager and corepack where supported.
  • Keep local and remote versions in sync and use frozen installs.

Next: vercel.json and netlify.toml