Understanding Volta
Volta’s job is to manage your JavaScript command-line tools, such as node, npm, yarn, or executables shipped as part of JavaScript packages.
Similar to package managers, Volta keeps track of which project (if any) you’re working on based on your current directory. The tools in your Volta toolchain automatically detect when you’re in a project that’s using a particular version of the tools, and take care of routing to the right version of the tools for you.
Managing your toolchain
You control the tools managed by your Volta toolchain with two commands: volta install and volta uninstall.
Installing Node engines
To install a tool to your toolchain, you set the default version of that tool. Volta will always use this default, unless you’re working within a project directory that has configured Volta to use a different version. When you choose a default version, Volta will also download that version to the local cache.
For example, you can select an exact version of node to be your default version:
volta install node@20.11.0
You don’t need to specify a precise version, in which case Volta will choose a suitable version to match your request:
volta install node@20
You can also specify latest—or even leave off the version entirely, and Volta will choose the latest LTS release:
volta install node
Once you’ve run one of these commands, the node executable provided by Volta in your PATH environment (or Path in Windows) will, by default, automatically run your chosen version of Node.
Similarly, you can choose versions of the npm and Yarn package managers with volta install npm and volta install yarn, respectively. These tools will run using the default version of Node you selected.
Installing package binaries
With Volta, installing a command-line tool globally with your package manager also adds it to your toolchain. For example, the vuepress package includes an executable of the same name:
yarn global add vuepress
When you install a package to your toolchain, Volta takes your current default Node version and pins the tool to that engine (see Package Binaries for more information). Volta won’t change the tool’s pinned engine unless you update the tool, no matter what. This way, you can be confident that your installed tools don’t change behind your back.
Managing your project
Volta allows a team or community of collaborators to standardize on the development tools they use for their project.
Pinning Node engines
The volta pin command allows you to choose your Node engine and package manager versions for a project:
volta pin node@18.19
volta pin yarn@1.19
Volta stores this in your package.json so you can commit your choice of tools to version control:
"volta": {
"node": "18.19.0",
"yarn": "1.19.2"
}
This way, everyone who uses Volta to work on the project automatically gets the same version you selected.
node --version # 18.19.0
yarn --version # 1.19.2
Using project tools
The node and package manager executables aren’t the only smart tools in your toolchain: the package binaries in your toolchain are also aware of your current directory, and respect the configuration of the project you’re in.
For example, installing the Typescript package will add the compiler executable—tsc— to your toolchain:
npm install --global typescript
Depending on the project you’re in, this executable will switch to the project’s chosen version of TypeScript:
cd /path/to/project-using-typescript-4.9.3
tsc --version # 4.9.3
cd /path/to/project-using-typescript-5.3.3
tsc --version # 5.3.3
Safety and convenience
Because Volta’s toolchain always keeps track of where you are, it makes sure the tools you use always respect the settings of the project you’re working on. This means you don’t have to worry about changing the state of your installed software when switching between projects.
What’s more, Volta covers its tracks whenever it runs a tool, making sure your npm or Yarn scripts never see what’s in your toolchain.
These two features combined mean that Volta solves the problem of global packages. In other words, Volta gives you the convenience of global package installations, but without the danger.
For example, you can safely install TypeScript with npm i -g typescript—and enjoy the convenience of being able to call tsc directly from your console—without worrying that your project’s package scripts might accidentally depend on the global state of your machine.
Enjoy!