Complete Guide to Specifying Node.js Versions in Cloudflare Pages: From Basics to Advanced

For any frontend or full-stack developer, Cloudflare Pages is an incredibly attractive deployment platform. It’s fast, globally distributed, and seamlessly integrates with Git workflows. When deploying projects, if you don’t specify a Node.js version, it defaults to version 18.17.1. If your project depends on a higher Node.js version, you’ll encounter compilation errors during the build process. Ensuring your local development environment matches Cloudflare’s build environment exactly is crucial. The most critical aspect of this is precisely controlling the Node.js version.

Why is this so important?

• Consistency: Avoid the classic “it works on my machine” problem.
• Functionality: Use language features or tools that require specific Node.js versions.
• Security: Stay updated with Node.js versions that have fixed security vulnerabilities.

This guide will take you deep into all methods for specifying Node.js versions on Cloudflare Pages, from basic to advanced, and reveal some essential “gotchas” and “insider secrets” you need to know.

Core Methods: Specifying Node.js Versions

Cloudflare provides two main and officially supported ways to specify Node.js versions.

Method 1: Environment Variables ⚙️

This is the most direct and flexible approach, requiring no code changes.

1. Go to your Pages project dashboard.
2. Navigate to Settings > Environment variables.
3. In the Build environment variables section, click Add variable.
4. Set the variable name to NODE_VERSION.
5. Set the value to your desired specific version number, such as 20.11.1 or 18.17.1.
6. Save, and your next build will use the specified version.

This method is perfect for quickly switching or testing different Node.js versions without touching your codebase.

Method 2: Project Files 📄

This is a more “code-centric” approach that includes version information as part of your project’s version control, making it ideal for team collaboration.

You need to create a specific file in your project’s root directory. Cloudflare supports two file names that function identically:

• .nvmrc (following Node Version Manager convention)
• .node-version

The file content is extremely simple: just write the version number without any additional characters.

Correct example (.nvmrc):

20.11.1

Incorrect examples:

# Wrong! Don't add "v"
v20.11.1

# Wrong! Don't write as an assignment
NODE_VERSION=20.11.1

When you push changes containing this file to your Git repository, Cloudflare will automatically read and use the specified version during builds.

Priority Rules Revealed: What Takes Precedence When Multiple Methods Exist?

What happens if you specify versions in both environment variables and project files? While the official documentation doesn’t clearly state this, based on community experience and our research, the priority order is:

1. Project files (.nvmrc / .node-version): The build system first checks if version files exist in the repository.
2. Environment variables (NODE_VERSION): If no project files are found, the build system looks for environment variables.
3. Cloudflare default version: If neither of the above is set, it uses the default version from Cloudflare’s build system image (for example, v3 build system uses Node.js 22.x).

⚠️ Impact of wrangler.toml When your project includes a wrangler.toml file to configure Pages, it becomes the “single source of truth” for configuration, which may cause environment variables set in the Cloudflare UI (including NODE_VERSION) to be ignored.

Best Practice: If your project uses wrangler.toml, we strongly recommend using a .nvmrc file to lock the Node.js version—this is the most reliable method.

Common Pitfalls: Methods That Don’t Work ❌

To save you time and effort, remember these common configuration mistakes:

• engines field in package.json: Despite being a common practice in Node.js projects, Cloudflare Pages does not support determining Node.js versions through the engines field in package.json. The build process completely ignores it.
• LTS aliases: Using aliases like lts/hydrogen or lts/* in .nvmrc files will cause build failures. You must provide an exact numerical version number.

Beyond Node: Controlling Your Package Manager Versions

Build stability depends not only on Node.js but also on npm, yarn, or pnpm. Cloudflare also allows you to specify their versions through environment variables:

• NPM_VERSION
• YARN_VERSION
• PNPM_VERSION

This is very useful when resolving lockfile version mismatches or ensuring you use specific pnpm features.

Advanced Scenarios and Insider Secrets

Monorepo

In monorepo architectures, Node.js versions are set at the Pages project level, affecting the entire build environment. Even if your repository contains multiple applications, they will share the same Node.js version during builds.

Direct Uploads

If you choose “direct upload” instead of connecting a Git repository, Cloudflare’s build environment settings will not apply. This is because the build process happens on your local machine or in your own CI/CD pipeline. The Node.js version you use depends on the environment where you run the build.

Environment Variable Order Bug

This is a very subtle trick: in rare cases, the definition order of environment variables in the Cloudflare UI might affect results. Some developers have reported that when other variables (like HUGO_VERSION) are defined before NODE_VERSION, the NODE_VERSION gets ignored.

Troubleshooting tip: If your NODE_VERSION doesn’t seem to be taking effect, try dragging it to the top of the environment variables list, then redeploy.

Summary

Precisely controlling your build environment is key to ensuring your project runs stably and efficiently on Cloudflare Pages.

• Preferred method: For most projects, adding a .nvmrc file to your codebase is the best choice.
• Flexible alternative: Use the NODE_VERSION environment variable for quick testing and overrides.
• Beware of pitfalls: Forget about package.json engines.
• Advanced tips: Understand the impact of wrangler.toml and potential environment variable ordering issues.

I hope this guide helps you fully master Cloudflare Pages build configuration and gain a deeper understanding of Node.js version specification!