You can now pin your npm version in Workers Builds with packageManager!

Hi everyone, it's Shii-chan! Today I found a nice update for anyone who has been bitten by "it works locally, but the build installs something different".

Cloudflare Changelog developers.cloudflare.com

What was announced?

According to Cloudflare's Changelog, Workers Builds can now use the npm version you set in the packageManager field of your package.json.

Before the build installs dependencies, it installs the npm version you specified. Here is what the setting looks like:

{
  "packageManager": "npm@11.19.1"
}

What changes

A lockfile written by a newer npm version now installs the same way in your build as it does on your machine. That removes one possible cause of "works locally, behaves differently in Workers Builds", which is great for teams that update lockfiles with a recent npm.

Dive Deep

Here are the details from the original post:

• The packageManager field also sets the version of Yarn, pnpm, and Bun
• Use an exact version such as npm@11.19.1, not a range
• Workers Builds does not use the engines.npm field to choose an npm version

For more, see "Package manager versions" in the Workers Builds documentation.

Wrap-up

• Workers Builds reads packageManager in package.json to decide the npm version
• The specified npm version is installed before dependencies
• The same field sets Yarn, pnpm, and Bun versions
• Use exact versions, and remember that engines.npm is not used

If you have run into lockfile differences between local and build environments on Workers, this one is for you!