Corepack no Node.js

O Corepack no Node.js gerencia versões de package managers como pnpm e Yarn por projeto. Em vez de cada desenvolvedor instalar uma versão global diferente, o repositório declara o gerenciador e a versão no package.json. Corepack cria shims, baixa o binário necessário, valida integridade e executa a ferramenta compatível.

Essa abordagem melhora a reprodução de instalações e reduz erros causados por versões divergentes. Porém, o comportamento mudou nas versões recentes do Node.js: Corepack foi distribuído junto com o runtime até antes do Node.js 25 e pode precisar de instalação manual em ambientes novos. Por isso, a imagem Docker, o CI e a documentação do projeto devem instalar e ativar Corepack explicitamente.

Neste guia, você aprenderá a instalar Corepack, habilitar shims, declarar packageManager, usar pnpm ou Yarn, trabalhar offline, validar integridade e configurar CI e containers.

O que é Corepack?

O projeto oficial nodejs/corepack define Corepack como uma ponte entre projetos Node.js e os package managers usados no desenvolvimento. Ele intercepta comandos como pnpm e yarn, identifica a versão declarada e executa o binário correto.

Os gerenciadores suportados incluem:

• pnpm;
• Yarn;
• npm em comandos explícitos do Corepack.

Disponibilidade por versão

Corepack foi distribuído com Node.js a partir da linha 14.19 até antes da versão 25. Em runtimes que não incluem o utilitário, instale manualmente:

npm install --global corepack@latest

Fixe uma versão aprovada em ambientes controlados:

npm install --global corepack@0.34.0

Consulte o changelog antes de escolher o número exato.

Ativando os shims

corepack enable

O comando cria executáveis próximos ao Node.js. Depois:

pnpm --version
yarn --version

Em diretórios de sistema somente leitura, corepack enable pode falhar. Use uma imagem apropriada ou --install-directory em um caminho gravável.

Campo packageManager

{
  "name": "orders-api",
  "packageManager": "pnpm@10.13.1"
}

O valor deve conter nome e versão exata. Um hash de integridade pode ser incluído:

{
  "packageManager": "pnpm@10.13.1+sha224.HASH"
}

O hash ajuda a verificar que o binário baixado é o esperado.

Definindo a versão com corepack use

corepack use pnpm@10.13.1

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

corepack use yarn@4.9.2

Revise as mudanças no lockfile antes de commitá-las.

Por que não instalar pnpm globalmente?

Uma instalação global cria diferenças entre máquinas. Um desenvolvedor pode usar pnpm 9, outro pnpm 10 e o CI uma versão diferente. Mudanças de lockfile, resolução e configurações tornam o resultado imprevisível.

Com Corepack, o repositório declara a versão e todos executam o mesmo binário.

devEngines.packageManager

Corepack também reconhece:

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

Esse campo valida o ambiente de desenvolvimento. Quando o campo superior packageManager existe, ele continua sendo a referência principal para a versão usada.

Known Good Releases

Fora de um projeto configurado, Corepack utiliza versões consideradas conhecidas e boas. Atualize a versão global:

corepack install --global pnpm@10.13.1

Evite depender desse estado global dentro do projeto. Declare sempre packageManager.

Instalando a versão do projeto

corepack install

O comando baixa e prepara o gerenciador indicado no diretório atual.

Atualização dentro da mesma major

corepack up

Use para selecionar uma versão compatível na linha configurada. Para mudar de major:

corepack use pnpm@latest

Faça upgrades em pull request dedicado e execute CI completa.

pnpm com Corepack

corepack enable
corepack use pnpm@10.13.1
pnpm install --frozen-lockfile

Em monorepos, configure pnpm-workspace.yaml e mantenha o lockfile na raiz.

Yarn com Corepack

corepack enable
corepack use yarn@4.9.2
yarn install --immutable

Yarn moderno pode usar Plug’n’Play ou node_modules. Documente a estratégia para ferramentas e containers.

npm e Corepack

npm continua distribuído com Node.js por outro mecanismo e seus shims não são instalados por padrão. É possível executar:

corepack npm install

Na maioria dos projetos npm, a instalação nativa e npm Workspaces no Node.js já são suficientes.

CI com GitHub Actions

- uses: actions/checkout@v6

- uses: actions/setup-node@v4
  with:
    node-version: 24
    cache: pnpm

- run: npm install --global corepack@0.34.0
- run: corepack enable
- run: pnpm install --frozen-lockfile
- run: pnpm run lint
- run: pnpm test
- run: pnpm run build

Se a versão do Node.js já inclui Corepack, instalar explicitamente ainda torna o pipeline previsível. Consulte CI para Node.js com GitHub Actions.

Cache no CI

Cacheie o store do gerenciador, não node_modules inteiro. A chave deve considerar:

• SO;
• versão do Node.js;
• lockfile;
• versão do package manager.

Docker com Corepack

FROM node:24 AS build
WORKDIR /app

RUN npm install --global corepack@0.34.0 \
  && corepack enable

COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

COPY . .
RUN pnpm run build

Não use latest em builds reproduzíveis. Fixe Node.js, Corepack e o gerenciador.

Node.js 25 ou superior

Como Corepack não é mais incluído automaticamente nessas versões, a imagem precisa instalar o pacote:

RUN npm install --global corepack@0.34.0 \
  && corepack enable

Sem essa etapa, comandos pnpm ou yarn podem não existir.

Workflow offline

Prepare um archive em ambiente com rede:

corepack pack pnpm@10.13.1 \
  --output corepack-cache.tgz

No ambiente isolado:

corepack install --global \
  --cache-only corepack-cache.tgz

Esse fluxo é útil em redes restritas e builds herméticos.

corepack pack em containers

Uma imagem pode pré-carregar o gerenciador:

RUN corepack pack pnpm@10.13.1 \
  --output /tmp/corepack.tgz \
  && corepack install --global \
    --cache-only /tmp/corepack.tgz

Assim, o runtime não precisa acessar a rede para encontrar o binário.

COREPACK_ENABLE_NETWORK

COREPACK_ENABLE_NETWORK=0 pnpm install

Impede que Corepack baixe package managers. O cache precisa estar preparado. Isso não impede o próprio pnpm de acessar o registry de dependências.

COREPACK_HOME

export COREPACK_HOME="$HOME/.cache/corepack"

Use para controlar onde os binários são armazenados. Em CI, o diretório pode ser cacheado com cuidado.

Proxy e registry

Corepack reconhece configurações de proxy e variáveis específicas de registry. Não grave tokens em scripts ou imagens:

COREPACK_NPM_REGISTRY=https://registry.npmjs.org

Injete credenciais apenas durante o build e remova arquivos temporários.

Integridade

Não desative verificações com COREPACK_INTEGRITY_KEYS=0 como solução permanente. Um erro de assinatura deve ser investigado, porque ignorá-lo reduz a proteção da supply chain.

Veja Supply Chain no Node.js.

Strict mode

Por padrão, Corepack pode impedir o uso de um gerenciador diferente do declarado. Isso protege lockfiles e instalações.

COREPACK_ENABLE_STRICT=0

Desabilitar strict deve ser uma exceção temporária, não configuração compartilhada.

Atualizações automatizadas

Dependabot ou Renovate podem atualizar packageManager. Configure testes para confirmar:

• lockfile válido;
• instalação imutável;
• scripts;
• workspaces;
• Docker;
• publicação.

Monorepos

O package manager deve ser declarado na raiz. Pacotes internos não precisam escolher versões diferentes. Turborepo e Nx executam tarefas sobre o mesmo ambiente.

Consulte Turborepo no Node.js e Nx no Node.js.

Diagnóstico

corepack --version
corepack cache clean
DEBUG=corepack pnpm --version

Confirme também PATH, proxy, DNS, permissões e a versão do Node.js.

Erros comuns

• Assumir que Corepack sempre vem com Node: versões novas podem não incluir.
• Não executar enable: shims não existem.
• packageManager sem versão: ambiente não é determinístico.
• latest no Docker: build muda sem commit.
• Cache offline vazio: execução falha.
• Desativar integridade: supply chain fica vulnerável.
• Gerenciador global diferente: lockfile é alterado.
• Token no Dockerfile: segredo pode permanecer na camada.

Configuração recomendada

{
  "name": "orders-api",
  "private": true,
  "packageManager": "pnpm@10.13.1+sha224.HASH",
  "engines": {
    "node": ">=22 <26"
  },
  "scripts": {
    "check": "pnpm run lint && pnpm run typecheck && pnpm test",
    "build": "tsc -p tsconfig.build.json"
  }
}

Conclusão

O Corepack no Node.js fixa o package manager como parte do projeto. O campo packageManager, shims e verificação de integridade reduzem diferenças entre desenvolvedores, CI e Docker.

Instale Corepack explicitamente, especialmente em Node.js 25 ou superior, fixe versões e prepare cache offline quando necessário. Com essa disciplina, pnpm ou Yarn se tornam dependências reproduzíveis da mesma forma que o runtime e o código.