Primeiros passos com o vlt, uma alternativa ao npm

O vlt é um gerenciador de pacotes JavaScript gratuito e open source, criado por pessoas que desenvolveram e mantiveram o npm.

O vlt passou a ser uma opção séria com o lançamento da versão 1.0. Ele instala a partir do package.json, divide a instalação em uma etapa de download e uma etapa de scripts e traz uma linguagem de consulta para o seu grafo de dependências. O atrito está nos detalhes: lockfiles, autenticação via .npmrc, scripts de postinstall e, principalmente, o registry de onde vêm os seus pacotes. Este guia aborda todos esses pontos em um projeto existente e termina com um veredito claro.

O que é o gerenciador de pacotes vlt e quem o criou?

O vlt é um client de gerenciamento de pacotes acompanhado de um serviço de registry hospedado, e vem de pessoas que construíram o npm. O post de lançamento de novembro de 2024, assinado por Darcy Clarke, Ruy Adorno e Luke Karrys, o apresentou como gratuito e open source. O vlt 1.0 foi lançado em 4 de agosto de 2026, e versões 1.x vêm sendo publicadas desde então.

A CLI do vlt parecerá familiar para quem usa npm. A arquitetura, porém, é diferente. Se você está comparando com a outra principal alternativa ao npm, veja como o pnpm aborda os mesmos problemas.

Instale o vlt e execute-o em um projeto existente

Você pode instalar o vlt com o script oficial ou via npm. Depois disso, o vlt install baixa suas dependências e o vlt build executa os scripts delas.

# official installer, then configure a registry and account
curl -fsSL https://install.vlt.sh | bash
vlt setup

# or install through npm
npm install -g vlt

cd your-project
vlt install   # resolve, download, extract; no dependency scripts run
vlt build     # run lifecycle scripts for eligible packages

A instalação via npm consta no guia de migração do npm. É preciso configurar um registry antes que o vlt install funcione. A documentação de configuração informa que o vlt não vem com nenhum registry padrão, e qualquer comando que precise acessar um registry é interrompido com um erro de configuração até que você defina um.

Você vai trabalhar com dois arquivos na raiz do projeto:

• vlt.json: configuração do projeto, substituindo o .npmrc.
• vlt-lock.json: o lockfile do vlt.

Segundo o guia de migração do npm, o vlt não lê o package-lock.json. Ele resolve tudo do zero. Você pode excluir o lockfile antigo ou mantê-lo enquanto as duas ferramentas rodam lado a lado. Isso é menos suave do que a importação de lockfile do pnpm, abordada em migrando do npm para o pnpm. Compare as versões resolvidas antes de fazer qualquer merge.

O vlt é um substituto direto (drop-in)?

Trate o “drop-in” como algo a ser testado, não presumido. O post de lançamento de 2024 dizia que o vlt poderia substituir seu gerenciador de pacotes atual “na maioria dos casos”. O post da versão 1.0 vai além e chama o client de substituto drop-in do npm. Ambas as afirmações vêm do fornecedor. Verifique estas cinco áreas no seu próprio projeto:

1. Configurações do .npmrc. A documentação não diz que o vlt lê o .npmrc. As configurações de registry e de escopo ficam no vlt.json, em scoped-registries. Os tokens de autenticação vão no arquivo de keychain do vlt ou em variáveis de ambiente VLT_TOKEN, conforme descrito no guia de migração do npm. Escopos privados costumam ser o primeiro ponto em que uma migração quebra.
2. Pacotes com scripts de instalação. Addons nativos e pacotes que baixam um binário não funcionarão até que o vlt build seja executado (veja abaixo).
3. Peer dependencies. A documentação de instalação diz que o vlt busca manter uma única cópia de cada peer dependency. Se duas partes da árvore precisarem de versões de peer que não podem coexistir, o vlt dá a cada parte seu próprio contexto de peer. Árvores que falham com o erro ERESOLVE do npm podem ser resolvidas no vlt, possivelmente com mais de uma cópia do peer.
4. Workspaces. Monorepos têm uma página própria na documentação do vlt. Confira sua estrutura com base nela.
5. CI. Use vlt ci seguido de vlt build.

Uma regressão causada pela troca de gerenciador de pacotes pode passar no CI e só aparecer em produção. Uma versão transitiva diferente, ou um postinstall ignorado que deveria ter gerado um arquivo, pode surgir como um erro de runtime no navegador. O session replay com captura de console e rede relaciona esse erro ao deploy que alterou o lockfile.

O registry: de onde vêm seus pacotes

O client do vlt não tem registry padrão. Você escolhe um. A documentação de registries informa que os comandos de instalação (vlt install, vlt ci, vlx e outros) exigem que o alias de registry npm esteja definido. Um valor simples de registry vindo do vlt.json, de uma flag ou de VLT_REGISTRY não basta para eles. A outra opção é o vlt setup, que configura os registries da sua conta vlt.io.

Executar o vlt setup muda a origem dos seus pacotes. Ele aponta o alias npm para o mirror da sua conta no registry do vlt. A página inicial do vlt diz que toda requisição de um pacote público passa por uma verificação de segurança nesse mirror, que bloqueia malwares conhecidos. Sua raiz de confiança passa do npm para o vlt.

Para usar diretamente o registry público do npm, execute:

vlt config set registries=npm=https://registry.npmjs.org/

Executado dentro do projeto, esse comando grava o alias no vlt.json do projeto. Faça commit desse arquivo para que todo o time e o CI usem a mesma origem.

Uma ressalva: uma issue aberta em abril de 2026 relata que o vlt install continua usando as URLs de registry registradas em um vlt-lock.json existente. Se você trocar de registry, gere o lockfile novamente.

O bloqueio no registry só impede malwares que já foram identificados. Uma versão maliciosa recém-publicada ainda pode passar até que alguém a sinalize. Times que precisam de hospedagem privada também podem fazer self-hosting do vsr, o registry compatível com npm e sob licença Fair Source do vlt, que o post de lançamento oferece para uso local, self-hosted ou gerenciado.

Padrões de segurança: instalações em fases e vlt build

O vlt install não executa nenhum script de dependências. Em seguida, o vlt build executa os scripts de ciclo de vida de todos os pacotes que os possuem, exceto pacotes com alertas de malware conhecidos, a menos que você restrinja o alvo com um seletor. A documentação do build define o alvo padrão como:

:scripts:not(:built):not(:malware)

Não há prompt de aprovação. Você aprova scripts escrevendo uma consulta mais restrita em Dependency Selector Syntax. Passe-a como alvo do build, ou use --allow-scripts na instalação, e salve-a no vlt.json para que todo o time use a mesma. O anúncio do vlt build explica o modelo em detalhes.

Na prática, as instalações em fases significam que um pacote que precisa de um script de postinstall para baixar um binário pré-compilado ou compilar um addon nativo não é compilado após o vlt install. Qualquer coisa que dependa do binário ou dos arquivos gerados por ele pode falhar até que o vlt build seja executado. Inclua o vlt build em todos os scripts de setup e jobs de CI.

A ideia é a mesma de desabilitar os scripts de instalação do npm por padrão. Controles do lado do consumidor, porém, só protegem instalações. Do lado da publicação, verifique o conteúdo do pacote com npm pack --dry-run para não publicar arquivos sem querer.

Consultas ao grafo de dependências com vlt query

O vlt query seleciona pacotes no seu grafo de dependências resolvido usando seletores no estilo CSS, assim como o querySelectorAll seleciona elementos em uma página. O post da versão 1.0 contabiliza mais de 60 pseudo-seletores de grafo, cerca de 30 deles focados em segurança. O post sobre insights selectors do vlt informa que os seletores de segurança usam metadados do Socket.

vlt query ':scripts'                  # packages with install scripts
vlt query ':malware'                  # packages with known malware alerts
vlt query ':prod'                     # production dependencies only
vlt query ':scripts' --view=mermaid   # render matches as a Mermaid diagram

A documentação do query lista os modos de saída: human, json, mermaid, svg, png e count. Comece pelo :scripts, porque é dessa lista que o vlt build escolhe por padrão (depois ele ignora pacotes já compilados e pacotes com alertas de malware). Segundo o post sobre host context do vlt, o :host(local) executa uma consulta em todos os projetos configurados no dashboard do vlt.

Os mesmos seletores funcionam no CI:

- run: npm install -g vlt
- run: vlt ci          # vlt install --expect-lockfile
- run: vlt build
- name: Report dependencies with malware alerts
  run: vlt query ':malware' --view=count

Para fazer essa última etapa falhar o job, adicione --expect-results=0, descrito na documentação do query. A consulta é a mesma em todos os lugares: ela é a sua política, armazenada como uma única string de seletor.

Veredito: vale para um projeto paralelo, mas ainda não como padrão

Vale a pena experimentar o vlt em um projeto paralelo agora. Um time em produção deve manter seu gerenciador de pacotes atual até que seu próprio CI, a autenticação no registry privado e os pacotes com scripts de instalação funcionem sem problemas no vlt. As instalações em fases e o vlt query são úteis. A resolução de lockfile do zero e a escolha do registry exigem uma decisão consciente. Se o que mais importa para você é a velocidade de instalação, compare com a reescrita em Rust do pnpm 12 no seu próprio repositório.

Comece em uma branch. Defina explicitamente o alias de registry npm, execute vlt install, vlt build e vlt query ':scripts' e compare as versões resolvidas no vlt-lock.json com o seu lockfile antigo antes que qualquer coisa chegue à main.

Perguntas frequentes

Qual versão do Node.js o vlt exige, e ele ainda cria uma pasta node_modules?

O pacote vlt exige Node.js 22.22 ou superior. O vlt ainda cria um diretório node_modules, mas usa seu próprio layout interno em node_modules/.vlt/. Isso é diferente da árvore plana do npm. Por padrão, o vlt cria hard links dos arquivos a partir de um store global no Linux e descompacta cada pacote no macOS e no Windows; a configuração store-linker altera esse comportamento. Os pacotes continuam sendo resolvidos normalmente em runtime, então o código da sua aplicação não deve precisar de alterações.

O que substitui o npx e o npm run ao usar o vlt?

O vlt exec substitui o npx. Você também pode chamá-lo como vlt x ou com o atalho vlx. Ele executa o binário de um pacote e baixa o pacote se ele não estiver no node_modules, pedindo confirmação antes de buscar qualquer coisa nova. O vlxl executa apenas binários que já estão instalados. O vlt run, abreviado como vlr, executa scripts do package.json com seus hooks pre e post. Ambos aceitam um seletor --scope para direcionar a execução a workspaces.

Como migro os overrides do npm para o vlt?

O equivalente do vlt ao campo overrides do npm são os Graph Modifiers. Você os define no vlt.json e os escreve como consultas em Dependency Selector Syntax. Isso permite direcionar uma dependência por caminho, workspace ou intervalo semver, e não apenas pelo nome do pacote. Quando mais de um modifier corresponde à mesma dependência, o vlt usa regras de especificidade semelhantes às do CSS para decidir qual prevalece.

Como configuro workspaces em um monorepo com vlt?

O vlt lê o campo workspaces do package.json raiz como está, então um monorepo existente de npm ou yarn funciona sem alterações. Use o campo workspaces do vlt.json raiz quando quiser grupos nomeados ou estiver migrando do pnpm-workspace.yaml. Se o vlt.json tiver um campo workspaces, o vlt usa apenas ele e ignora o campo do package.json; os dois não são mesclados. No vlt.json, o valor pode ser uma string glob, um array de globs como packages/* ou um objeto de grupos nomeados, cada um mapeando para caminhos ou globs. Um array simples vai para o grupo padrão, chamado packages.