Gerencie dependencias com Claude Code: npm, pnpm, Yarn e CI

Gerenciar dependencias nao e sair atualizando tudo

Projetos JavaScript e TypeScript mudam rapido porque suas dependencias mudam rapido. React, Vite, TypeScript, ESLint, ferramentas de teste, SDKs, bibliotecas de UI e plugins de build podem transformar um app pequeno em uma arvore com centenas de pacotes diretos e transitivos.

Claude Code ajuda bastante, mas o uso seguro nao e pedir para ele rodar npm install pacote@latest sem contexto. O melhor caminho e pedir uma inspecao: qual package manager esta em uso, qual lockfile existe, quais dependencias estao antigas, quais vulnerabilidades aparecem, quais scripts precisam passar e quais updates major devem ser isolados.

Lockfile e o arquivo que fixa as versoes exatas instaladas. npm usa package-lock.json, pnpm usa pnpm-lock.yaml e Yarn usa yarn.lock. O package.json diz quais faixas sao aceitas; o lockfile diz o que realmente foi resolvido. Em CI, a regra e verificar esse resultado, nao reescrever o lockfile durante o build.

Para a parte de pipeline, veja tambem Claude Code CI/CD setup. Em repositorios com workspace, leia junto o guia de pnpm workspace com Claude Code.

---

Fluxo recomendado

Separe o processo em inventario, plano, PR de atualizacao, CI e decisao humana.

flowchart LR
  scan["Inventario\noutdated / audit"] --> plan["Plano\npatch / minor / major"]
  plan --> pr["PR de atualizacao\nRenovate / Dependabot"]
  pr --> ci["CI\ninstall / test / build"]
  ci --> review["Revisao com Claude Code\nriscos e evidencias"]
  review --> merge["Decisao humana\nmerge ou rejeicao"]

O primeiro prompt deve impedir edicoes.

claude -p "
Inspect dependency management in this repository. Do not edit files yet.
Report package manager, lockfile, outdated direct dependencies,
security audit command, scripts that must pass, and risky major updates.
Return file paths and exact commands.
"

Esse formato evita mudancas grandes antes de entender o repositorio. Primeiro se faz o inventario; depois se escolhe o que atualizar.

---

npm, pnpm e Yarn

Nao misture package managers. Cada ferramenta tem um lockfile e um comando de CI adequado.

Ferramenta	Lockfile	Instalacao em CI	Desatualizados	Auditoria
npm	package-lock.json	npm ci	npm outdated	npm audit --audit-level=high
pnpm	pnpm-lock.yaml	pnpm install --frozen-lockfile	pnpm outdated --format table	pnpm audit --audit-level high
Yarn modern	yarn.lock	yarn install --immutable	yarn up -i ou yarn up <pattern>	yarn npm audit --recursive --severity high

A documentacao do npm descreve npm ci como comando para ambientes automatizados e informa que ele falha quando package.json e lockfile nao batem. pnpm usa --frozen-lockfile; Yarn usa --immutable. O PR altera o lockfile, e a CI prova que ele e reproduzivel.

---

Script pronto para copiar

Salve como scripts/verify-deps.mjs. Ele detecta npm, pnpm ou Yarn, faz instalacao congelada, auditoria high e roda typecheck, test e build se existirem.

#!/usr/bin/env node
import { existsSync, readFileSync } from "node:fs";
import { spawnSync } from "node:child_process";

function readPackageJson() {
  return JSON.parse(readFileSync("package.json", "utf8"));
}

function detectPackageManager(pkg) {
  const declared = pkg.packageManager || "";
  if (declared.startsWith("pnpm@")) return "pnpm";
  if (declared.startsWith("yarn@")) return "yarn";
  if (declared.startsWith("npm@")) return "npm";
  if (existsSync("pnpm-lock.yaml")) return "pnpm";
  if (existsSync("yarn.lock")) return "yarn";
  if (existsSync("package-lock.json")) return "npm";
  throw new Error("No package manager or lockfile detected.");
}

function run(command, args) {
  const label = [command, ...args].join(" ");
  console.log(`\n$ ${label}`);
  const result = spawnSync(command, args, {
    stdio: "inherit",
    shell: process.platform === "win32",
  });
  if (result.status !== 0) throw new Error(`Command failed: ${label}`);
}

const pkg = readPackageJson();
const manager = detectPackageManager(pkg);

const installCommands = {
  npm: ["npm", ["ci"]],
  pnpm: ["pnpm", ["install", "--frozen-lockfile"]],
  yarn: ["yarn", ["install", "--immutable"]],
};

const auditCommands = {
  npm: ["npm", ["audit", "--audit-level=high"]],
  pnpm: ["pnpm", ["audit", "--audit-level", "high"]],
  yarn: ["yarn", ["npm", "audit", "--recursive", "--severity", "high"]],
};

const scriptCommands = {
  npm: (name) => ["npm", ["run", name]],
  pnpm: (name) => ["pnpm", ["run", name]],
  yarn: (name) => ["yarn", ["run", name]],
};

run(...installCommands[manager]);
run(...auditCommands[manager]);

for (const name of ["typecheck", "test", "build"]) {
  if (pkg.scripts?.[name]) run(...scriptCommands[manager](name));
  else console.log(`\n- skip ${name}: script not found`);
}

console.log(`\nDependency verification passed with ${manager}.`);

No package.json:

{
  "scripts": {
    "deps:verify": "node scripts/verify-deps.mjs"
  }
}

Esse script verifica, nao atualiza. Assim todo PR passa pela mesma regra, seja feito por Claude Code, Renovate, Dependabot ou por uma pessoa.

---

Tres usos praticos

Primeiro: updates patch/minor de ferramentas de desenvolvimento. ESLint, Prettier, Vite, Vitest e TypeScript podem ser agrupados quando o risco e baixo. Updates major ficam separados.

claude -p "
Prepare a dependency update plan for devDependencies only.
Group patch and minor updates for lint/test/build tools.
Do not update major versions.
Run the dependency verification script after changes.
"

Segundo: vulnerabilidades. Nao comece com audit fix --force. Leia o JSON e peca para Claude Code separar dependencia direta, transitiva, versao instalada, versao corrigida, possibilidade de lockfile-only e necessidade de major.

npm audit --json
pnpm audit --json
yarn npm audit --recursive --json

Terceiro: workspace ou monorepo. packages/ui nao deve importar apps/web, e dependencias internas devem usar workspace:*. Tambem e comum duplicar React, TypeScript ou ESLint sem perceber.

claude -p "
Inspect this workspace before dependency updates.
Find packages/* importing from apps/*, internal dependencies not using workspace:*,
duplicated versions of react/typescript/eslint, and scripts that should use filters.
Do not edit files.
"

---

Renovate e Dependabot

Renovate e bom quando as regras precisam ser mais finas. Esta configuracao deixa major para revisao humana e permite automerge de devDependencies patch/minor apos CI.

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "dependencyDashboard": true,
  "lockFileMaintenance": {
    "enabled": true,
    "schedule": ["before 5am on monday"],
    "automerge": true
  },
  "packageRules": [
    {
      "matchManagers": ["npm"],
      "matchDepTypes": ["devDependencies"],
      "matchUpdateTypes": ["patch", "minor"],
      "automerge": true
    },
    {
      "matchUpdateTypes": ["major"],
      "labels": ["dependency", "major-update"],
      "automerge": false
    }
  ]
}

Dependabot e suficiente para muitos repositorios no GitHub.

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    groups:
      dev-tooling:
        dependency-type: "development"
        update-types:
          - "minor"
          - "patch"

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "monthly"

Tambem inclua GitHub Actions. Se actions/setup-node ou actions/checkout ficam antigos, a propria verificacao de dependencias envelhece.

---

CI de verificacao

name: dependency-check

on:
  pull_request:
  push:
    branches: [main]

jobs:
  verify-dependencies:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: corepack enable
      - run: node scripts/verify-deps.mjs

Cache pode vir depois. Primeiro garanta que a instalacao sem estado escondido funciona.

---

Armadilhas comuns

A primeira armadilha e usar npm install em CI. Use npm ci. A segunda e usar audit fix --force antes de classificar o problema. A terceira e juntar varios updates major no mesmo PR. A quarta e revisar apenas package.json e ignorar o lockfile. A quinta e tratar devDependencies e dependencies como o mesmo risco. A sexta aparece em sites de conteudo: mudancas em MDX, CSS ou build podem quebrar blocos de codigo, anuncios ou CTAs. O fluxo de verificacao ajuda nisso.

---

Prompt para revisar PR

claude -p "
Review this dependency update PR.
Focus on package.json, lockfile, CI config, and test output.
Report updated packages, direct vs transitive changes, major updates,
peer dependency changes, commands that passed or failed, and manual checks.
Do not change files unless there is a blocking issue.
"

Uma boa revisao de dependencias deixa evidencias: o que mudou, o que passou, o que falhou e o que precisa de olho humano.

---

Referencias e proximos passos

Veja npm ci, npm audit, pnpm install, pnpm audit, yarn install, yarn npm audit, Claude Code CLI, Dependabot options e Renovate automerge.

Para continuar, leia auditoria de seguranca com Claude Code e boas praticas de CLAUDE.md. Para adaptar a um repositorio real de equipe, use a pagina de treinamento e consultoria.

Resultado ao testar

O ganho principal foi separar geracao de updates e verificacao. Claude Code planeja e revisa, mas deps:verify e o diff do lockfile decidem se o PR esta pronto. Tirar updates major do automerge tambem torna as falhas muito mais faceis de investigar.