Corepack no Node.js

Corepack é uma ferramenta que conecta projetos Node.js ao gerenciador de pacotes e à versão exata escolhida pela equipe. Em vez de depender de uma instalação global diferente em cada máquina, o projeto registra a versão de npm, pnpm ou Yarn no package.json. Quando um comando é executado, Corepack seleciona e baixa a versão correta, valida sua integridade e a reutiliza pelo cache.

Esse mecanismo melhora a reprodutibilidade. Um desenvolvedor não precisa adivinhar qual versão do gerenciador gerou o lockfile, e o pipeline de CI não depende da versão instalada na imagem base. Também reduz erros causados por mudanças de formato, resolução de dependências ou comportamento entre versões do mesmo gerenciador.

Como instalar Corepack atualmente

Corepack foi distribuído junto com Node.js a partir da versão 14.19 até antes da versão 25. Em instalações mais recentes, pode ser necessário instalá-lo manualmente:

npm install -g corepack@latest
corepack --version

Se a máquina já possui Yarn ou pnpm instalados globalmente, remova esses binários para evitar conflitos:

npm uninstall -g yarn pnpm

No Windows, uma instalação antiga vinda do instalador MSI do Node.js pode precisar ser removida pela opção de modificação do aplicativo antes da instalação global pelo npm.

Ativando os shims

O comando abaixo cria os atalhos para os gerenciadores suportados:

corepack enable

Depois, comandos como pnpm e yarn passam por Corepack. Ele analisa o projeto atual, encontra a configuração do gerenciador e executa a versão correspondente.

Em sistemas com diretórios somente leitura, corepack enable pode falhar ao gravar os shims ao lado do executável. Nesse caso, instale em um diretório gravável ou crie aliases de shell que chamem corepack pnpm e corepack yarn.

Fixando a versão no package.json

O campo principal é packageManager:

{
  "name": "minha-api",
  "private": true,
  "packageManager": "pnpm@10.15.1"
}

Também é possível incluir um hash de integridade, o que reduz o risco de usar um artefato diferente do esperado:

{
  "packageManager": "pnpm@10.15.1+sha224.HASH_AQUI"
}

Para configurar automaticamente uma versão, use:

corepack use pnpm@10.15.1

O comando atualiza o package.json, baixa a versão e executa a instalação. Para Yarn:

corepack use yarn@4.9.2

Validação com devEngines

Corepack também reconhece devEngines.packageManager. Essa configuração permite definir o comportamento quando alguém usa um gerenciador incompatível:

{
  "devEngines": {
    "packageManager": {
      "name": "pnpm",
      "version": "10.15.1",
      "onFail": "error"
    }
  }
}

Com onFail igual a error, o processo é interrompido. warn apenas exibe um aviso, e ignore não impede a execução. Para equipes, falhar cedo costuma ser melhor que permitir uma instalação diferente e descobrir o problema depois.

Fluxo diário de desenvolvimento

Após a configuração, os desenvolvedores usam o gerenciador normalmente:

pnpm install
pnpm test
pnpm build

Corepack intercepta o comando, verifica o campo packageManager e garante a versão. Se o projeto declara pnpm e alguém tenta usar Yarn, a ferramenta pode bloquear a execução para evitar alteração indevida do lockfile.

Atualizando dentro da mesma versão principal

Para buscar a versão mais recente compatível dentro da linha configurada:

corepack up

Para mudar de versão principal, informe explicitamente:

corepack use pnpm@latest

Essa alteração deve passar por pull request. Revise o lockfile, execute testes e registre a mudança, pois uma atualização do gerenciador pode alterar a resolução de dependências.

Known Good Releases

Quando um projeto não declara um gerenciador, Corepack usa versões conhecidas como boas. É possível atualizar essas referências globalmente:

corepack install -g

Em projetos profissionais, não dependa desse fallback. Registre sempre packageManager, porque o objetivo é tornar o ambiente determinístico.

Corepack em CI

Um pipeline pode instalar Corepack, ativar os shims e executar o gerenciador fixado:

steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: 24
  - run: npm install -g corepack@latest
  - run: corepack enable
  - run: pnpm install --frozen-lockfile
  - run: pnpm test

A instalação explícita é importante em versões do Node.js que não incluem Corepack. Fixe também a versão da própria ferramenta quando precisar de máxima previsibilidade.

Uso em imagens Docker

Em uma imagem, instale e prepare o gerenciador antes de copiar todo o código:

FROM node:24-alpine AS deps
WORKDIR /app
RUN npm install -g corepack@latest && corepack enable
COPY package.json pnpm-lock.yaml ./
RUN corepack install
RUN pnpm install --frozen-lockfile

FROM deps AS build
COPY . .
RUN pnpm build

corepack install baixa o gerenciador configurado no projeto. O cache da camada reduz downloads em builds posteriores.

Ambientes sem acesso à internet

Corepack oferece um fluxo para preparar um arquivo com o gerenciador:

corepack pack pnpm@10.15.1 -o corepack.tgz

No ambiente isolado:

corepack install -g --cache-only ./corepack.tgz

Isso é útil em redes restritas, imagens endurecidas e processos de build que não podem acessar o registro durante a execução.

Controle de rede

A variável abaixo impede downloads automáticos:

export COREPACK_ENABLE_NETWORK=0

Ao desativar a rede, o cache precisa conter todas as versões necessárias. Caso contrário, o comando falha, o que é preferível a baixar algo inesperado em um ambiente controlado.

Cache e diagnóstico

Para limpar o cache:

corepack cache clean

Para logs detalhados:

DEBUG=corepack pnpm install

Problemas comuns envolvem proxy, DNS, certificados corporativos, permissões no diretório de cache e shims antigos no PATH.

Segurança e integridade

O hash no campo packageManager adiciona validação do artefato. Não desative verificações de integridade em produção. A variável COREPACK_INTEGRITY_KEYS pode alterar esse comportamento, mas ignorar validação reduz a proteção da cadeia de suprimentos.

Use versões exatas, revise atualizações e mantenha o lockfile versionado. Corepack protege a versão do gerenciador; o lockfile protege o grafo de dependências. Os dois mecanismos são complementares.

Corepack com monorepos

Em um monorepo, o campo packageManager deve ficar na raiz. Todos os workspaces usam a mesma versão. Isso evita que pacotes internos sejam instalados por ferramentas diferentes.

Combine Corepack com npm Workspaces no Node.js, contratos de pacote com Exports e Imports no Node.js, proteção de cadeia de suprimentos em Supply Chain no Node.js e automação com GitHub Actions no Node.js.

Quando vale a pena

Corepack é especialmente útil quando a equipe usa pnpm ou Yarn, mantém monorepos, possui múltiplos ambientes ou precisa reproduzir builds antigos. Mesmo projetos pequenos ganham consistência ao registrar a versão do gerenciador.

Consulte o repositório oficial do Corepack e a página oficial de versões do Node.js para confirmar como a ferramenta é distribuída na versão usada pelo projeto.