Cloudflare Pages Node/Yarn versions

I spent an hour today debugging this error which occurs when deploying a Github repo to Cloudflare Pages:

07:50:42.633    Success: Finished cloning repository files
07:50:43.436    Detected the following tools from environment: yarn@3.6.3, nodejs@18.17.1
07:50:43.438    Installing project dependencies: yarn
07:50:44.208    ➤ YN0070: Migrating from Yarn 1; automatically enabling the compatibility node-modules linker 👍
07:50:44.211    
07:50:44.264    ➤ YN0000: ┌ Resolution step
07:50:48.645    ➤ YN0032: │ fsevents@npm:2.3.3: Implicit dependencies on node-gyp are discouraged
07:50:52.853    ➤ YN0000: └ Completed in 8s 590ms
07:50:52.879    ➤ YN0000: ┌ Post-resolution validation
07:50:52.879    ➤ YN0028: │ The lockfile would have been modified by this install, which is explicitly forbidden.
07:50:52.880    ➤ YN0000: └ Completed
07:50:52.880    ➤ YN0000: Failed with errors in 8s 618ms

It turns out that Cloudflare Pages has two versions of Ubuntu (20 and 22) and each version comes bundled with specific versions of Node and Yarn. I was using Yarn v1 on my local machine and Cloudflare Pages was using Ubuntu 22 which in turn uses Yarn v3.

I was stumped by the error because Cloudflare Pages works for other projects that I use Yarn v1 for locally. It turns out that you can pick your version of Ubuntu under Settings > Build & Deployments > Build System Version.

The way Cloudflare picks the Ubuntu version for you project appears based on the node version required in package.json and for Vite this is:

  "engines": {
    "node": "^14.18.0 || >=16.0.0"
  },

Ubuntu 20 uses Node version 12.x, so I believe Cloudflare chose Ubuntu 22 due to my project requiring Node 14.x/16.x.

Locally I use Node 16.14 and Yarn 1.22. Because Node and Yarn versions are tied together on Cloudflare pages, you need to configure your local environment to reflect either the Ubuntu 20 or Ubuntu 22 configuration: Either use Node 12.x + Yarn 1.x OR Node >=14.x/16.x + Yarn 3.x