Switching Between Projects

One of the key benefits of Volta is its seamless handling of different tool versions across projects. This page explains how Volta automatically manages your JavaScript environment as you move between projects.

Automatic Version Switching

Unlike other version managers that require you to manually switch between tool versions, Volta handles this automatically based on your current directory.

How It Works

1. When you run a JavaScript command (like node, npm, or a package binary), Volta's shim intercepts the command
2. Volta checks your current directory to see if you're in a project with pinned tool versions
3. If you are, Volta uses the pinned versions from that project's package.json
4. If you're not in a project with pinned versions, Volta uses your default tools

All of this happens transparently without any additional commands.

Example Workflow

Imagine you have two projects with different Node.js requirements:

Project A (~/projects/project-a/package.json):

{
  "volta": {
    "node": "14.19.1",
    "npm": "6.14.16"
  }
}

Project B (~/projects/project-b/package.json):

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

Your workflow might look like this:

# In Project A
cd ~/projects/project-a
node --version  # Shows v14.19.1
npm --version   # Shows v6.14.16

# Switch to Project B
cd ~/projects/project-b
node --version  # Automatically shows v16.14.2
npm --version   # Automatically shows v8.5.0

# Outside of any project
cd ~
node --version  # Shows your default Node version

Nested Projects

If you have nested projects, Volta will use the tool versions from the nearest package.json with a volta section.

For example:

/parent-project/package.json (has volta section with node@14)
/parent-project/child-project/package.json (has volta section with node@16)
/parent-project/other-directory/ (no package.json)

If you run commands in:

• /parent-project/child-project/ - Volta uses Node.js 16
• /parent-project/other-directory/ - Volta uses Node.js 14
• /parent-project/ - Volta uses Node.js 14

Package Binaries

Volta's automatic switching also applies to package binaries. For example, if you have a project-specific version of TypeScript and run tsc, Volta ensures that the correct version is used.

Global vs. Local Packages

When you run a package binary:

1. If the binary exists in your project's node_modules/.bin/, Volta uses that version
2. If not, but the package is installed globally via Volta, it uses that version
3. Otherwise, it shows an error that the command wasn't found

Troubleshooting

If you're experiencing issues with version switching:

• Verify your project has a volta section in its package.json
• Run volta list all to check your installed tools
• Check that the tools you need are either pinned to your project or installed as default versions
• Run volta which node to see which version of Node.js Volta is using and why