pnpm vs npm

As diferenças práticas entre pnpm e npm - como eles instalam pacotes, gerenciam espaço em disco, lidam com lockfiles e quando escolher um em vez do outro.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Instalar pnpm (requer Node.js 18.12+)
corepack enable
corepack prepare pnpm@latest --activate
 
# Ou instalar via npm
npm install -g pnpm
 
# Verificar
pnpm --version
 
# Comandos comuns - lado a lado
npm install           # pnpm install
npm install react     # pnpm add react
npm install -D vitest # pnpm add -D vitest
npm uninstall react   # pnpm remove react
npm run dev           # pnpm dev  (ou pnpm run dev)
npm test              # pnpm test
npx create-next-app   # pnpm create next-app  (ou pnpm dlx create-next-app)

Quando usar isso: Ao iniciar um novo projeto ou avaliar se deve mudar de npm para pnpm. Entender os prós e contras ajuda você a fazer uma escolha informada, em vez de mudar com base em "hype".

Análise Detalhada

Como o npm Instala Pacotes

O npm usa uma estrutura node_modules plana. Quando você executa npm install, ele:

1. Lê package.json para dependências diretas.
2. Resolve a árvore completa de dependências (dependências das dependências).
3. Eleva (hoists) o máximo de pacotes possível para o nível superior de node_modules/ para reduzir a duplicação.
4. Escreve package-lock.json para travar versões exatas.

node_modules/
  react/
  react-dom/
  scheduler/        # dependência do react-dom, elevada para o nível superior
  loose-envify/     # dependência transitiva, também elevada

O problema com a elevação: seu código pode import pacotes que não estão no seu package.json porque eles foram elevados. Isso é chamado de dependências fantasmas - seu código funciona por acidente até que alguém remova o pacote que trouxe a dependência transitiva.

Como o pnpm Instala Pacotes

O pnpm usa um store de endereçamento por conteúdo e links simbólicos. Quando você executa pnpm install, ele:

1. Baixa pacotes para um store global (~/.local/share/pnpm/store/ no macOS/Linux).
2. Cria um store virtual dentro de node_modules/.pnpm/ com hard links para o store global.
3. Cria links simbólicos em node_modules/ que apontam apenas para suas dependências diretas.

node_modules/
  react -> .pnpm/react@19.1.0/node_modules/react
  react-dom -> .pnpm/react-dom@19.1.0/node_modules/react-dom
  .pnpm/
    react@19.1.0/
      node_modules/
        react/          # hard link para o store global
    react-dom@19.1.0/
      node_modules/
        react-dom/      # hard link para o store global
        scheduler/      # link simbólico para .pnpm/scheduler@.../

Este layout significa:

• Você não pode importar pacotes que não declarou em package.json - sem dependências fantasmas.
• Cada versão de um pacote é armazenada uma única vez no disco em todos os seus projetos.
• node_modules é menor e as instalações são mais rápidas porque os arquivos são linkados, não copiados.

Principais Diferenças

Economia de Espaço em Disco

Com o npm, se você tem 10 projetos que usam React 19, o React é copiado 10 vezes. Com o pnpm, o React 19 é armazenado uma vez no store global e hard-linkado em cada projeto. Em uma máquina com muitos projetos, o pnpm pode economizar gigabytes de espaço em disco.

# Ver quanto espaço o store do pnpm está usando
pnpm store status
 
# Limpar pacotes não referenciados do store
pnpm store prune

Velocidade de Instalação

O pnpm é consistentemente mais rápido que o npm por várias razões:

• Hard links em vez de cópias de arquivos.
• Downloads paralelos com requisições de rede concorrentes.
• Store de endereçamento por conteúdo significa que pacotes baixados anteriormente estão disponíveis instantaneamente.

Benchmarks típicos mostram o pnpm 2-3x mais rápido que o npm em instalações frias e significativamente mais rápido em instalações quentes (quando os pacotes já estão no store).

Rigidez e Segurança

O layout estrito do node_modules do pnpm pega bugs reais:

// Isso funciona com npm (dependência fantasma), mas falha com pnpm:
import chalk from 'chalk';
// Erro: chalk não está listado em package.json

Se o seu código só funciona por causa da elevação do npm, o pnpm exporá a dependência ausente imediatamente. Isso é um recurso, não um bug - significa que seu package.json é uma descrição precisa do que seu projeto realmente usa.

Suporte a Monorepo

Tanto npm quanto pnpm suportam workspaces, mas a implementação do pnpm é mais madura:

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

# Executar um comando em um workspace específico
pnpm --filter @myapp/web dev
 
# Instalar uma dependência em um workspace específico
pnpm --filter @myapp/web add zod
 
# Executar um comando em todos os workspaces
pnpm -r build

O flag --filter do pnpm é mais poderoso que o flag --workspace do npm, suportando padrões glob, filtragem baseada em dependência e filtragem de mudanças desde o commit.

Comparação de Comandos

Migrando de npm para pnpm

# 1. Instalar pnpm
corepack enable
corepack prepare pnpm@latest --activate
 
# 2. Excluir artefatos do npm
rm -rf node_modules package-lock.json
 
# 3. Instalar com pnpm
pnpm install
 
# 4. (Opcional) Fixar a versão do pnpm em package.json
# Adicionar: "packageManager": "pnpm@9.15.4"
 
# 5. Atualizar seus scripts - npm run -> pnpm
# Atualizar configuração de CI (GitHub Actions, etc.)

A migração geralmente é indolor. Se falhar, é quase sempre por causa de dependências fantasmas - pacotes que seu código importa, mas que estão faltando em package.json. Corrija-os adicionando os pacotes ausentes explicitamente.

Quando Usar npm

• Você quer configuração zero. O npm vem com o Node.js. Nada extra para instalar.
• Você está seguindo um tutorial. A maioria dos tutoriais e documentações usa comandos npm. Traduzir para pnpm é trivial, mas adiciona atrito ao aprender.
• Sua equipe usa npm e não há problemas. Mudar de gerenciador de pacotes no meio de um projeto tem um custo. Se o npm está funcionando bem, não há razão urgente para mudar.
• O cache de CI já está otimizado para npm. Alguns provedores de CI têm melhor cache embutido para node_modules e package-lock.json.

Quando Usar pnpm

• Você trabalha em muitos projetos. A economia de espaço em disco é substancial.
• Você quer correção estrita de dependências. Sem dependências fantasmas significa menos surpresas em produção.
• Você gerencia um monorepo. O suporte a workspaces e filtragem do pnpm é o melhor da categoria.
• A velocidade de instalação importa. Instalações mais rápidas significam CI mais rápida e integração de desenvolvedores mais rápida.
• Você quer impor um gerenciador de pacotes específico. Corepack + "packageManager" em package.json garante que todos usem a mesma ferramenta e versão.

Armadilhas

1. Dependências fantasmas quebram na migração. Se seu código importa um pacote não listado em package.json, ele funciona com npm, mas falha com pnpm. A correção é adicionar o pacote ausente a package.json - isso é a coisa certa a fazer de qualquer maneira.
2. Alguns pacotes assumem node_modules plano. Pacotes mais antigos que usam truques de require.resolve ou percorrem a árvore de diretórios podem falhar com o layout linkado simbolicamente do pnpm. A solução alternativa é node-linker=hoisted em .npmrc, mas isso anula a rigidez do pnpm.
3. Formato do lockfile é diferente. npm usa package-lock.json (JSON). pnpm usa pnpm-lock.yaml (YAML). Você não pode usar ambos - escolha um e adicione o outro a .gitignore.
4. npx não existe no pnpm. Use pnpm dlx em vez disso. Exemplo: pnpm dlx create-next-app em vez de npx create-next-app.
5. Rigidez de peer dependency. pnpm é mais rigoroso com peer dependencies do que npm. Se um pacote espera react como peer dependency e você não o instalou, pnpm avisa ou dá erro. Corrija instalando a peer dependency.
6. Configuração de CI difere. GitHub Actions e outros provedores de CI precisam de pnpm/action-setup ou Corepack para instalar pnpm antes de executar pnpm install.
7. Localização do store global. O store global do pnpm pode crescer bastante com o tempo. Execute pnpm store prune periodicamente para limpar pacotes não mais referenciados por nenhum projeto.

Alternativas

FAQs

Relacionados

• Instalando Node.js e npm
• Executando Scripts Node.js em JavaScript
• Módulos ESM vs CommonJS