Volta no Node.js

O Volta no Node.js gerencia versões do runtime e ferramentas JavaScript por projeto. Em vez de executar manualmente um comando para trocar de Node.js antes de entrar em cada repositório, Volta lê a configuração do package.json e seleciona automaticamente a versão correta.

A ferramenta também instala CLIs globais de forma estável, associando cada binário a uma versão do Node.js. Isso reduz problemas em que uma atualização do runtime faz comandos globais desaparecerem ou passarem a executar com uma versão incompatível.

Neste guia, você aprenderá a instalar Volta, fixar Node.js e package managers, controlar ferramentas globais, configurar projetos, usar CI e comparar Volta com Corepack, nvm e imagens Docker.

O que é Volta?

A documentação oficial do Volta apresenta a ferramenta como um gerenciador rápido e multiplataforma para engines e CLIs JavaScript. Ela funciona em Windows e shells Unix e usa shims no PATH para selecionar o executável correto.

Principais recursos:

• troca automática por projeto;
• suporte multiplataforma;
• instalação estável de ferramentas globais;
• pin de versões no package.json;
• Node.js, npm, Yarn e pnpm em fluxos suportados;
• execução temporária com versões específicas.

Como os shims funcionam?

Volta coloca executáveis intermediários no PATH. Quando você executa node, npm ou uma CLI instalada, o shim descobre:

1. se o diretório atual pertence a um projeto configurado;
2. qual versão foi fixada;
3. qual ferramenta precisa ser usada;
4. qual Node.js deve executar a ferramenta.

Essa resolução não depende de hooks específicos do shell e funciona ao abrir um novo terminal.

Instalação no Linux e macOS

curl https://get.volta.sh | bash

Em ambientes corporativos, não execute scripts remotos sem revisar. Baixe o instalador, valide checksums e fixe a versão aprovada.

Instalação no Windows

Use o instalador oficial disponibilizado pelo projeto. Depois, abra um novo terminal e confirme:

volta --version

Configurando o PATH

O comando:

volta setup

ajusta arquivos de configuração do shell quando necessário. Verifique:

volta which node
volta which npm

Instalando Node.js

volta install node@22

Esse comando define a versão padrão da sua ferramenta pessoal. Para uma versão exata:

volta install node@22.18.0

Evite depender apenas da major quando a equipe precisa de builds idênticos.

Fixando Node.js no projeto

Dentro do repositório:

volta pin node@22.18.0

Volta adiciona uma seção ao package.json:

{
  "volta": {
    "node": "22.18.0"
  }
}

Depois do commit, qualquer colaborador com Volta executa automaticamente essa versão dentro do projeto.

Pin do npm

volta pin npm@11.5.2

{
  "volta": {
    "node": "22.18.0",
    "npm": "11.5.2"
  }
}

Fixar npm reduz mudanças de lockfile causadas por versões diferentes.

Yarn e pnpm

Volta oferece suporte a package managers conforme a versão e a configuração adotada. Consulte a documentação atual para pnpm, pois algumas integrações podem exigir habilitação específica.

Para projetos modernos, combine o pin do Node.js com Corepack no Node.js quando quiser declarar pnpm ou Yarn pelo campo packageManager.

Volta e packageManager

Um projeto pode usar as duas configurações:

{
  "packageManager": "pnpm@10.13.1",
  "volta": {
    "node": "22.18.0"
  }
}

Volta seleciona o Node.js; Corepack seleciona a versão do pnpm. Mantenha responsabilidades claras para não declarar versões conflitantes em vários lugares.

Engines

Também defina o contrato do pacote:

{
  "engines": {
    "node": ">=22 <23"
  }
}

engines comunica compatibilidade aos consumidores. volta define o ambiente de desenvolvimento exato.

Ferramentas globais estáveis

Instale uma CLI:

volta install typescript
volta install eslint
volta install serve

Volta associa a ferramenta ao Node.js usado na instalação. Uma mudança posterior do Node padrão não obriga a reinstalar tudo.

Versão específica de uma ferramenta

volta install typescript@5.9.2

Para ferramentas do projeto, ainda prefira devDependencies e scripts locais. CLIs globais são adequadas para utilitários pessoais, não para garantir builds de equipe.

Listando ferramentas

volta list
volta list all

Use para diagnosticar qual versão está instalada e quais ferramentas pertencem ao toolchain.

Descobrindo o executável

volta which node
volta which eslint

O comando mostra o caminho resolvido e ajuda a identificar conflitos de PATH.

Execução temporária

volta run --node 20 node --version

Também é possível executar um comando com package manager específico, conforme as opções da versão:

volta run --node 20 --npm 10 npm test

Isso é útil para confirmar compatibilidade sem alterar o pin do projeto.

Testando múltiplas versões

Uma biblioteca pode validar:

volta run --node 20 npm test
volta run --node 22 npm test
volta run --node 24 npm test

No CI, uma matrix costuma ser mais adequada. Consulte CI para Node.js com GitHub Actions.

Instalação automática da versão

Ao entrar em um projeto com versão não disponível, Volta baixa a engine necessária. Em ambientes sem rede, prepare o cache previamente.

Cache e diretório VOLTA_HOME

Por padrão, Volta usa um diretório no perfil do usuário. A variável:

VOLTA_HOME="$HOME/.volta"

define a localização. O PATH inclui:

$VOLTA_HOME/bin

Em CI, cachear todo o diretório pode acelerar jobs, mas a chave precisa considerar sistema operacional e configuração.

CI com GitHub Actions

Em pipelines, actions/setup-node já oferece uma forma direta de escolher a versão. O CI não precisa obrigatoriamente instalar Volta:

- uses: actions/setup-node@v4
  with:
    node-version: 22.18.0
    cache: npm

Para evitar duplicação, leia a versão do package.json com um script ou use uma action confiável que suporte Volta.

Usando Volta no CI

Quando quer reproduzir exatamente o ambiente local:

- run: curl https://get.volta.sh | bash
- run: echo "$HOME/.volta/bin" >> "$GITHUB_PATH"
- run: volta install node@22.18.0
- run: npm ci
- run: npm test

Fixe e valide o instalador; não use um script mutável sem controle em pipelines críticos.

Docker

Em imagens Docker, o tag da imagem normalmente já fixa Node.js:

FROM node:22.18.0-slim

Instalar Volta dentro da imagem costuma ser desnecessário. O container deve ter um único runtime definido no Dockerfile.

Veja Docker Multi-stage para Node.js.

Dev Containers

Volta pode ser útil dentro de um Dev Container quando vários projetos compartilham a mesma imagem. Porém, uma imagem específica por repositório pode fixar o runtime diretamente. O próximo artigo apresenta Dev Containers.

Monorepos

O pin no package.json raiz vale para o workspace. Evite versões diferentes de Node.js entre pacotes do mesmo processo de build.

Consulte npm Workspaces no Node.js, Turborepo no Node.js e Nx no Node.js.

Volta versus nvm

nvm altera o ambiente do shell e normalmente exige nvm use ou integração automática. Volta usa shims e troca por projeto sem comando manual.

Diferenças práticas:

• Volta funciona nativamente no Windows;
• Volta registra versões no package.json;
• nvm possui ecossistema e uso histórico amplos;
• nvm permite shells com versões independentes;
• Volta gerencia CLIs globais de forma estável.

Volta versus fnm

fnm é um gerenciador rápido de versões do Node.js, geralmente integrado ao shell. Volta acrescenta pin de ferramentas e roteamento de CLIs. Escolha com base no fluxo da equipe.

Volta versus Corepack

Volta gerencia principalmente Node.js e toolchain. Corepack gerencia versões de pnpm e Yarn. Eles podem ser complementares.

Migração de .nvmrc

Leia a versão:

cat .nvmrc

Depois:

volta pin node@22.18.0

Mantenha .nvmrc durante uma transição quando parte da equipe ainda usa nvm. Garanta que os dois arquivos indiquem a mesma versão.

Atualizando o projeto

volta pin node@24.1.0

Faça a atualização em pull request dedicado:

1. atualize o pin;
2. atualize engines;
3. regenere lockfile se necessário;
4. execute lint e typecheck;
5. execute testes;
6. reconstrua imagens;
7. valide dependências nativas.

Ferramentas locais continuam preferíveis

Não substitua:

npm install --save-dev eslint

por uma expectativa de que todos instalarão ESLint globalmente. O projeto deve carregar sua própria versão e executar:

npm run lint

Segurança

• Baixe apenas do domínio oficial.
• Valide instaladores.
• Fixe versões do Node.js.
• Não use CLIs globais para builds críticos.
• Proteja o PATH.
• Revise hooks corporativos.
• Atualize Volta conscientemente.

Diagnóstico de PATH

which node
volta which node
node --version
volta list

No Windows:

where node

Se outro gerenciador aparece antes de Volta no PATH, remova ou ajuste a ordem.

Conflito com nvm

Executar nvm e Volta no mesmo shell pode alterar o PATH de formas inesperadas. Escolha um gerenciador principal. Durante migração, documente a ordem e evite inicializar ambos automaticamente.

Desinstalação

Siga o guia oficial para remover shims, diretório e entradas do shell. Não apague apenas o binário deixando PATH e caches órfãos.

Erros comuns

• Pin apenas da major: máquinas recebem patches diferentes.
• CLI global no build: versão não está no lockfile.
• Volta e nvm juntos: PATH muda inesperadamente.
• Docker com Volta desnecessário: imagem fica complexa.
• CI usa outra versão: local e pipeline divergem.
• engines ausente: consumidores não conhecem suporte.
• Corepack conflitante: package manager é declarado duas vezes.
• Instalador remoto sem validação: supply chain fica vulnerável.

Configuração recomendada

{
  "name": "orders-api",
  "private": true,
  "engines": {
    "node": ">=22 <23"
  },
  "packageManager": "pnpm@10.13.1",
  "volta": {
    "node": "22.18.0"
  },
  "scripts": {
    "check": "pnpm run lint && pnpm run typecheck && pnpm test",
    "build": "pnpm run check && tsc -p tsconfig.build.json"
  }
}

Conclusão

O Volta no Node.js transforma a versão do runtime em uma configuração do projeto. Os shims selecionam automaticamente a engine correta e mantêm ferramentas globais associadas a um ambiente estável.

Fixe versões exatas, mantenha ferramentas do projeto em devDependencies e alinhe CI e Docker. Com Corepack para package managers e Volta para Node.js, equipes reduzem diferenças de ambiente sem depender de comandos manuais ao trocar de repositório.