Configuration

Volta uses several configuration files to manage your JavaScript toolchain. This reference explains the available configuration options and their formats.

Project Configuration

Project-specific configurations are stored in your project's package.json file under the volta key.

Format

{
  "volta": {
    "node": "16.14.2",
    "npm": "8.5.0",
    "yarn": "1.22.19",
    "extends": "../shared-volta-config.json"
  }
}

Properties

Property	Type	Description
node	String	The version of Node.js to use in this project
npm	String	The version of npm to use in this project
yarn	String	The version of Yarn to use in this project
pnpm	String	The version of pnpm to use in this project
extends	String	Path to a shared Volta configuration file

Version Format

Version strings in the volta configuration can use the following formats:

• Exact version: 16.14.2
• Major version only: 16
• Major and minor: 16.14
• Version ranges (npm semver): ^16.14.0
• Tags: latest, lts

Shared Project Configuration

You can create shared Volta configurations that multiple projects can extend. This is useful for organizations that want to standardize tool versions across projects.

Format

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

The format is the same as the volta section in package.json, but at the root level of the JSON file.

User Configuration

Volta's user configuration is stored in the Volta home directory:

• Unix: ~/.volta/
• Windows: %LOCALAPPDATA%\Volta\

Tool Storage

Installed tools are stored in structured directories:

• Node.js: ~/.volta/tools/image/node/
• Package managers: ~/.volta/tools/image/yarn/, ~/.volta/tools/image/npm/
• Packages: ~/.volta/tools/user/packages/

Hooks Directory

Custom hooks are stored in ~/.volta/hooks/. See the Advanced Features section for more details.

Environment Variables

Environment variables provide another way to configure Volta's behavior. See the Environment Variables page for a complete reference.

Configuration Precedence

When resolving which tool version to use, Volta checks sources in the following order:

1. Command-line arguments (e.g., volta run --node 14)
2. Project configuration in the nearest package.json with a volta section
3. User's default tool versions (set via volta install)
4. Bundled versions (e.g., the npm that comes bundled with Node.js)

Examples

Typical Project Configuration

{
  "name": "my-project",
  "version": "1.0.0",
  "volta": {
    "node": "16.14.2",
    "npm": "8.5.0"
  },
  "dependencies": {
    // ...
  }
}

Extended Configuration

// shared-config.json
{
  "node": "16.14.2",
  "yarn": "1.22.19"
}

// package.json
{
  "name": "my-project",
  "version": "1.0.0",
  "volta": {
    "extends": "./shared-config.json",
    "npm": "8.5.0"  // Overrides any npm version in the extended config
  }
}

Workspace Configuration

For workspace-based projects, the root package.json configuration applies to all workspace packages:

// Root package.json
{
  "name": "workspace-root",
  "volta": {
    "node": "16.14.2",
    "yarn": "1.22.19"
  },
  "workspaces": [
    "packages/*"
  ]
}

// packages/app/package.json - will use Node.js 16.14.2 and Yarn 1.22.19
{
  "name": "app",
  "version": "1.0.0",
  // No volta section needed here
}