Uma Introdução ao pnpm: Uma Alternativa Mais Rápida ao npm e Yarn

Se você já assistiu seu pipeline de CI/CD gastar minutos instalando dependências ou teve problemas com espaço em disco em máquinas de desenvolvimento devido a pacotes duplicados entre projetos, você está experimentando exatamente os problemas que o pnpm foi projetado para resolver. Este gerenciador de pacotes performático oferece uma abordagem fundamentalmente diferente para o gerenciamento de dependências que pode reduzir os tempos de instalação em 2-3× e diminuir o uso de disco em aproximadamente 50%.

O Que Torna o pnpm Diferente

Diferentemente do npm e Yarn, que duplicam pacotes entre projetos, o pnpm usa um armazenamento endereçável por conteúdo com hard links para compartilhar dependências globalmente. Quando você instala o Express em múltiplos projetos, o npm cria cópias separadas em cada pasta node_modules. O pnpm o armazena uma vez em ~/.pnpm-store e cria hard links para essa cópia única, reduzindo drasticamente o uso de disco enquanto mantém isolamento completo entre projetos.

Esta arquitetura também previne “dependências fantasma”—um problema comum onde o código pode acidentalmente importar pacotes não listados no package.json. Com a resolução estrita de módulos Node.js do pnpm, se uma dependência não está explicitamente declarada, seu código não pode acessá-la, detectando erros antes que cheguem à produção.

Instalação e Configuração

Para Node.js 16.13 ou posterior, o método de instalação recomendado usa o Corepack:

corepack enable
corepack prepare pnpm@latest --activate

Alternativamente, instale via npm:

npm install -g pnpm

Comandos Essenciais para o Desenvolvimento Diário

Os comandos principais do pnpm espelham a sintaxe familiar do npm enquanto adicionam otimizações de desempenho:

pnpm add express          # Adicionar dependência de produção
pnpm add -D typescript    # Adicionar dependência de desenvolvimento
pnpm remove lodash       # Remover pacote
pnpm update             # Atualizar todas as dependências
pnpm run build         # Executar script do package.json

O comando pnpm store fornece funcionalidade única para gerenciar o cache global de pacotes:

pnpm store status      # Verificar saúde do armazenamento
pnpm store prune      # Remover pacotes não referenciados

Configuração para Projetos Modernos

Crie um arquivo .npmrc para configurar o comportamento do pnpm para sua equipe:

strict-peer-dependencies=true
auto-install-peers=true
prefer-offline=true

Essas configurações impõem requisitos de peer dependencies, instalam automaticamente peer dependencies (Node.js 16+) e priorizam pacotes em cache para acelerar instalações.

Configuração de Workspace para Monorepos

Para projetos monorepo, o suporte a workspaces do pnpm se destaca no gerenciamento de múltiplos pacotes. Crie um arquivo pnpm-workspace.yaml:

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

Vincule pacotes do workspace usando o protocolo workspace: no package.json:

{
  "dependencies": {
    "@myapp/shared": "workspace:*",
    "@myapp/ui": "workspace:^1.0.0"
  }
}

Execute comandos em todos os pacotes do workspace:

pnpm -r build                  # Compilar todos os pacotes
pnpm --filter @myapp/api dev   # Executar script dev em pacote específico

Otimização de CI/CD

Para GitHub Actions, use a action oficial do pnpm com Node.js 22 LTS:

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

Para GitLab CI, configure o cache para maximizar a otimização de CI/CD:

image: node:22

before_script:
  - corepack enable
  - corepack prepare pnpm@latest --activate

cache:
  key: pnpm-store-$CI_COMMIT_REF_SLUG
  paths:
    - .pnpm-store

install:
  script:
    - pnpm config set store-dir .pnpm-store
    - pnpm install --frozen-lockfile

A flag --frozen-lockfile garante builds reproduzíveis ao falhar se o pnpm-lock.yaml não corresponder ao package.json, prevenindo divergências entre ambientes de desenvolvimento e produção.

Desempenho na Prática

Equipes migrando do npm tipicamente veem velocidades de instalação melhorarem em 2-3× devido à estratégia eficiente de vinculação do pnpm. Um projeto de tamanho médio com 500 dependências pode levar 60 segundos com npm, mas apenas 20-25 segundos com pnpm. A economia de disco é ainda mais dramática—desenvolvedores trabalhando em múltiplos projetos frequentemente recuperam 5-10GB de espaço à medida que pacotes duplicados são eliminados.

Conclusão

O pnpm cumpre sua promessa de gerenciamento de dependências mais rápido e eficiente através de arquitetura inovadora em vez de melhorias incrementais. Sua resolução estrita de dependências detecta erros precocemente, enquanto as capacidades de configuração de workspace o tornam ideal para arquiteturas monorepo modernas. Seja otimizando pipelines de CI/CD ou gerenciando aplicações full-stack complexas, o pnpm fornece o desempenho e confiabilidade que equipes de desenvolvimento precisam sem sacrificar compatibilidade com o ecossistema npm existente.

Perguntas Frequentes

Como o pnpm lida com peer dependencies de forma diferente do npm?

O pnpm impõe resolução estrita de peer dependencies por padrão. Ele não instalará automaticamente peer dependencies a menos que você habilite auto-install-peers na sua configuração. Isso previne conflitos de versão e garante que seu projeto declare explicitamente todas as dependências necessárias.

Posso usar o pnpm com projetos npm ou Yarn existentes?

Sim, o pnpm é totalmente compatível com projetos npm e Yarn. Simplesmente execute pnpm import no diretório do seu projeto para gerar um arquivo pnpm-lock.yaml a partir do seu arquivo de lock existente. Todos os seus scripts npm e configurações do package.json funcionam sem modificação.

O que acontece com o armazenamento global quando desinstalo pacotes?

Os pacotes permanecem no armazenamento global mesmo após desinstalá-los dos projetos. Isso permite reinstalação instantânea se necessário posteriormente. Execute pnpm store prune periodicamente para remover pacotes não referenciados e liberar espaço em disco.

O pnpm é adequado para deployments de produção?

Absolutamente. O pnpm está pronto para produção e é usado por grandes empresas. Use pnpm install --frozen-lockfile em produção para garantir versões exatas de dependências. As instalações determinísticas e a resolução estrita de dependências na verdade tornam os deployments mais confiáveis do que com gerenciadores de pacotes tradicionais.