Noções Básicas de Gerenciadores de Pacotes

8 exemplos para você começar com Gerenciadores de Pacotes - 6 básicos e 2 intermediários.

Pré-requisitos

• Node.js 24.18.0 (Active LTS) instalado.
• Um diretório de projeto novo: mkdir my-api && cd my-api && npm init -y.
• Escolha um gerenciador por repositório e confirme o lockfile dele.

Exemplos Básicos

1. Instalar uma Dependência de Runtime com npm

Adicione uma dependência de produção e registre a versão exata resolvida em package-lock.json.

npm install express@5

• npm install <pkg> grava em dependencies e atualiza package-lock.json.
• npm 10+ vem com Node 24; nenhuma instalação separada é necessária.
• Use majors exatos em package.json quando precisar de atualizações previsíveis.

Relacionado: Lockfiles e Instalações Reproduzíveis - Instalações seguras para CI

2. Instalar uma Dependência de Desenvolvimento

Mantenha ferramentas de tempo de compilação fora dos pacotes de produção usando --save-dev.

npm install --save-dev typescript@5.6

• Dependências de desenvolvimento são omitidas quando NODE_ENV=production e você executa npm ci --omit=dev.
• TypeScript pertence a devDependencies para serviços de backend compilados em tempo de compilação.
• Fixe o major em package.json; deixe o lockfile fixar o patch.

Relacionado: Scripts do package.json - conecte scripts build e typecheck

3. Executar um Pacote Único Sem Instalar

Execute CLIs sem poluir package.json usando npx.

npx --yes tsx src/index.ts

• npx baixa para um cache, executa o binário e sai.
• --yes pula o prompt de instalação em CI e scripts.
• Prefira uma devDependency quando você executa a mesma CLI em cada compilação.

4. Verificar Pacotes Desatualizados

Exiba a divergência entre os intervalos do package.json e o registro.

npm outdated

• Colunas mostram a atual, a desejada (dentro do intervalo) e a mais recente (pode ser um major bump).
• Execute semanalmente em repositórios ativos; combine com npm audit para correções de segurança.
• Não execute npm update cegamente na sexta à tarde sem um teste.

Relacionado: Cadeia de Suprimentos: npm audit & Socket - controle atualizações arriscadas

5. Usar pnpm para Monorepos Eficientes em Disco

pnpm armazena pacotes uma vez no disco e os vincula a cada projeto através de um store com endereço de conteúdo.

corepack enable
corepack prepare pnpm@latest --activate
pnpm init
pnpm add fastify@5

• Hard links significam que 10 serviços não duplicam 10 cópias de lodash.
• O layout node_modules/.pnpm é mais rigoroso; dependências fantasmas são mais difíceis de depender acidentalmente.
• Habilite corepack para que CI e laptops usem a mesma versão do pnpm.

Relacionado: Workspaces & Monorepos - protocolo workspace:*

6. Usar Yarn Berry com Zero-Installs (Opcional)

Yarn Modern (v4) suporta Plug'n'Play e caches opcionais verificados para CI rápida.

corepack enable
yarn init -2
yarn add zod

• Os padrões do Berry diferem do Classic Yarn v1; leia o guia de migração antes de mudar.
• Zero-installs trocam o tamanho do repositório por um yarn install mais rápido em CI.
• Adote apenas se a equipe se comprometer com ferramentas e documentação específicas do Yarn.

Exemplos Intermediários

7. Forçar Versão do Node com engines

Rejeite instalações em versões não suportadas do Node antes de surpresas em tempo de execução.

{
  "engines": {
    "node": ">=24.18.0 <25"
  }
}

# .npmrc na raiz do repositório
engine-strict=true

• engines documenta o runtime suportado; engine-strict faz o npm falhar em caso de incompatibilidade.
• Espelhe a verificação em CI com node --version e npm ci.
• Alinhe com a política LTS da sua plataforma (Node 24 Active LTS em 2026).

Relacionado: engines & engine-strict - aplicação local e em CI

8. Escolher npm vs pnpm vs Yarn para Sua Equipe

Matriz de decisão para serviços TypeScript de backend.

• Padronize em um gerenciador por organização ou monorepo; lockfiles mistos quebram a CI.
• npm 10+ é excelente para a maioria dos serviços de API Node 24.
• Reavalie a escolha quando o número de workspaces exceder ~5 deployables.

Relacionado: Melhores Práticas de Gerenciadores de Pacotes - política de um lockfile

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.