Using .nvmrc files with Build Pipeline

Last updated on 7th January 2026

The .nvmrc file is a configuration file used by NVM (Node Version Manager) to specify which version of Node.js should be used for a project. This article explains how these files are handled in DeployHQ's build pipeline.

What is .nvmrc?

An .nvmrc file is a simple text file placed in the root of your repository that contains a Node.js version number. For example:

18.20.6

Or you can use version ranges:

18

This file is commonly used in development environments to ensure all developers use the same Node.js version.

How DeployHQ handles .nvmrc files

Important: DeployHQ's build pipeline currently ignores .nvmrc files during builds. This is intentional to prevent conflicts between your project's version specifications and DeployHQ's language version configuration.

When a build runs, DeployHQ temporarily renames version manager configuration files (including .nvmrc, .node-version, .ruby-version, .python-version, and .tool-versions) to prevent auto-loading. These files are renamed by appending .original to the filename (e.g., .nvmrc becomes .nvmrc.original) and are automatically restored after the build completes.

This design ensures that DeployHQ's language version settings take precedence over project-level version files, providing consistent and predictable build behavior.

Since .nvmrc files are not used during builds, DeployHQ provides three alternative methods to specify your Node.js version:

Configure the Node.js version through the DeployHQ UI in your project's Build Configuration:

  1. Navigate to your project's Build Pipeline
  2. Click Build Configuration
  3. Select your desired Node.js version from the dropdown (versions 8 through 25 are available)

This applies the selected version to all builds for your project.

2. Server-Specific Build Configurations

For projects that need different Node.js versions per environment (staging vs. production), use server-specific build configurations:

  1. Navigate to Server Build Configurations in your project
  2. Create separate configurations for different servers or server groups
  3. Specify different Node.js versions for each configuration

3. Custom Node.js versions with NVM

For Node.js versions not available in the dropdown, use the pre-installed NVM (Node Version Manager) 0.40.3:

source /opt/nvm/nvm.sh
nvm install 23.5.0
nvm use 23.5.0
node --version
npm install
npm run build

See How do I install a custom version of NodeJS for more details.

4. Using .deploybuild.yaml

You can also specify Node.js versions in a .deploybuild.yaml file:

build_languages:
  - name: "node"
    version: "20"

build_commands:
  - description: "Build application"
    command: "npm install \n npm run build"
    halt_on_error: true

Why are .nvmrc files ignored?

DeployHQ ignores .nvmrc and other version manager files to:

  1. Prevent conflicts: Avoid conflicts between project-level version files and DeployHQ's configured versions
  2. Ensure consistency: Provide predictable build behavior regardless of files in your repository
  3. Centralize control: Keep version management in DeployHQ's UI where it can be managed across environments

If version manager files were automatically loaded, they could override your carefully configured build settings, leading to unexpected behavior or build failures.

Migration from .nvmrc

If your project currently uses .nvmrc files, you can migrate to DeployHQ's version management:

  1. Check your .nvmrc version: Note the Node.js version specified in your .nvmrc file
  2. Configure in DeployHQ: Set the same version in your project's Build Configuration language dropdown
  3. Keep .nvmrc for local development: You can keep .nvmrc in your repository for local development - it won't interfere with DeployHQ builds

The .nvmrc file will continue to work for local development while DeployHQ uses its own configuration during builds.

Technical details

During the build process, DeployHQ's build server:

  1. Before build: Renames .nvmrc to .nvmrc.original (and other version files)
  2. During build: Uses the Node.js version configured in DeployHQ
  3. After build: Automatically restores .nvmrc.original back to .nvmrc

This happens transparently and doesn't affect your repository - the renamed files exist only in the build container and are never committed back to your repository.

Frequently asked questions

Q: Can I make DeployHQ read my .nvmrc file? A: Not currently. DeployHQ intentionally ignores these files to ensure consistent build behavior. Use the language version dropdown or NVM commands instead.

Q: Should I remove .nvmrc from my repository? A: No need to remove it. The file can remain in your repository for local development use. It will be ignored during DeployHQ builds but will still work for developers using NVM locally.

Q: What if I need different versions per branch? A: You can use server-specific build configurations to assign different versions to different deployment environments. For per-branch control, consider using .deploybuild.yaml files which can vary by branch.

Q: Why does my build log show a different Node.js version than my .nvmrc? A: This is expected behavior. DeployHQ uses the version configured in your Build Configuration, not the version in .nvmrc.