Pinning Node Versions

One of Volta's most powerful features is the ability to pin specific tool versions to your project, ensuring that everyone working on the project uses exactly the same toolchain.

Why Pin Versions?

• Consistency: Everyone on your team uses the same versions
• Reproducibility: Build environments match development environments
• Reliability: No surprises from unexpected tool behavior
• Onboarding: New team members automatically get the correct setup

How to Pin Node.js

To pin a specific Node.js version to your project:

volta pin node@16.14.2

This command:

1. Downloads and installs Node.js 16.14.2 (if not already present)
2. Updates your package.json with a volta section
3. Makes the project use Node.js 16.14.2 whenever you run node in the project directory

Your package.json will now contain:

{
  "volta": {
    "node": "16.14.2"
  }
}

Pinning Package Managers

You can also pin specific versions of package managers:

volta pin npm@8.5.0
volta pin yarn@1.22.18
volta pin pnpm@7.0.0

This ensures everyone uses the same package manager version, preventing lockfile inconsistencies and other versioning issues.

After pinning npm, your package.json will look like:

{
  "volta": {
    "node": "16.14.2",
    "npm": "8.5.0"
  }
}

Using Pinned Tools

Once tools are pinned, no additional commands are needed. Simply navigate to your project directory and run commands normally:

# These will use your project's pinned versions
node --version
npm --version

Volta automatically detects when you're in a directory with pinned versions and uses them instead of your default tools.

Updating Pinned Versions

To update a pinned version:

volta pin node@latest
volta pin npm@latest

Or specify a new version:

volta pin node@18

Best Practices

When to Pin

• For production applications: Always pin both Node and your package manager
• For libraries/packages: Pin Node if your code relies on specific Node features
• For tools/utilities: Pin the minimum Node version required for functionality

Version Selection

• For applications, choose an LTS (Long Term Support) version of Node
• For libraries, use the oldest Node version you want to support
• Periodically update versions to benefit from security fixes

CI/CD Integration

Make sure your CI/CD pipelines respect your pinned versions:

• Use the Volta GitHub Action in GitHub workflows
• For other CI systems, install Volta and it will automatically use your pinned versions