Você Deve Trocar do npm para o pnpm?

Você provavelmente já viu o pnpm mencionado em configurações de monorepo, configs de CI e documentações de frameworks. Talvez um colega jure por ele. Mas será que vale a pena enfrentar o atrito da troca para o seu trabalho frontend do dia a dia, ou ele está resolvendo problemas que você ainda não tem?

Aqui está o que você realmente precisa saber.

O Que Torna o pnpm Diferente do npm

O pnpm não é apenas um npm mais rápido. As verdadeiras diferenças são estruturais.

O npm cria um diretório node_modules plano, o que significa que seu código pode acidentalmente importar pacotes que você nunca declarou como dependências — um problema chamado de dependências fantasmas. O pnpm utiliza um armazenamento endereçável por conteúdo com hard links e symlinks, de modo que apenas suas dependências declaradas ficam acessíveis no nível raiz. Isso torna a resolução de dependências mais rigorosa e reproduzível.

A outra grande diferença é o uso de disco. O pnpm armazena cada versão de pacote uma única vez globalmente e cria hard links para seus projetos. Se você mantém múltiplos projetos Next.js ou Vite localmente, não está duplicando centenas de megabytes por projeto.

Para uma análise mais aprofundada do modelo de armazenamento e isolamento de dependências, vale a pena dar uma olhada na comparação oficial pnpm vs npm.

pnpm 11 e a Virada com Foco em Segurança

O pnpm 11, lançado em abril de 2026, dá continuidade a uma tendência que vem sendo construída ao longo das versões majoritárias recentes: priorizar segurança e determinismo em vez de velocidade pura.

O comportamento mais importante a conhecer antes de fazer a troca: o pnpm agora bloqueia scripts de ciclo de vida de dependências por padrão, a menos que sejam explicitamente aprovados. Esse é o fluxo pnpm approve-builds introduzido no pnpm 10. Se você instalar um pacote com um script postinstall — comum em pacotes que compilam binários nativos, como sharp, esbuild ou canvas — a instalação será bem-sucedida, mas o script não será executado até que você o aprove.

Isso surpreende desenvolvedores que esperam que tudo simplesmente funcione. Execute pnpm approve-builds interativamente ou configure as dependências de build permitidas no pnpm-workspace.yaml:

onlyBuiltDependencies:
  - sharp
  - esbuild

É uma troca deliberada: mais atrito no início, menos surpresas na cadeia de suprimentos depois.

Workspaces e Ferramentas para Monorepos

É aqui que o pnpm se destaca de forma notável. Os workspaces do npm funcionam, mas a implementação de workspaces do pnpm é mais ergonômica para configurações maiores.

Você define os pacotes em um arquivo pnpm-workspace.yaml:

packages:
  - 'apps/*'
  - 'packages/*'

E então obtém uma filtragem poderosa de fábrica:

pnpm --filter @myapp/ui build
pnpm --filter "...^@myapp/ui" test  # roda testes em pacotes que dependem do ui

Para equipes que utilizam Turborepo ou Nx, o protocolo de workspace do pnpm (workspace:*) se integra de forma limpa e mantém as dependências internas explícitas.

Fixando Versões com o Campo packageManager

Um passo prático, independentemente de você usar Corepack ou não: adicione um campo packageManager ao seu package.json para sinalizar qual gerenciador de pacotes e versão seu projeto espera.

{
  "packageManager": "pnpm@11.0.0"
}

O Corepack pode impor isso em ambientes onde está habilitado, mas mesmo sem o Corepack, ele comunica claramente a intenção para sua equipe e configuração de CI.

Integração com CI usando GitHub Actions

- uses: pnpm/action-setup@v6
  with:
    version: 11
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: 'pnpm'
- run: pnpm install --frozen-lockfile

Sempre use --frozen-lockfile no CI. Isso evita mutações silenciosas no lockfile e torna as instalações determinísticas.

A documentação oficial de CI do pnpm também inclui exemplos para GitHub Actions, GitLab CI, CircleCI, Azure Pipelines e Bitbucket Pipelines.

Quando Vale a Pena Trocar

O pnpm faz mais sentido se você está trabalhando em um monorepo, gerenciando muitos projetos locais ou quer um isolamento de dependências mais rigoroso por padrão. O modelo de segurança do pnpm approve-builds é genuinamente útil para equipes que se preocupam com a higiene da cadeia de suprimentos.

Se você está mantendo uma aplicação de pacote único e o npm está funcionando bem, o atrito da migração provavelmente não vale a pena. Os workspaces do npm são maduros o suficiente para configurações simples, e o padrão do ecossistema ainda tem valor real.

Conclusão

A resposta honesta: experimente o pnpm em um novo projeto primeiro. A interface de comandos é quase idêntica, o lockfile é legível, e a maioria dos frameworks frontend — incluindo Next.js, Vite e Astro — o suportam sem configuração extra. Se a rigidez e a economia de disco se encaixarem no seu fluxo de trabalho, escalar para projetos existentes se torna uma decisão muito menor.

Perguntas Frequentes

Understand every bug

Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.