Skill de Upgrade do Node

Q: Big bang ou rolling por serviço?

Rolling por serviço em monorepos após PR1-2 serem aplicados em toda a plataforma. Menor risco do que atualizar todos os handlers na mesma hora.

Q: Pular releases ímpares atuais?

Sempre mire apenas em Active LTS para produção. Releases ímpares são para adotantes iniciais, não para upgrades de frota.

Etapas de migração LTS e matriz de breaking changes - uma Skill de Agente para atualizar frotas de backend Node.js para 24.18.0 (Active LTS).

O Que Esta Skill Faz

A partir da versão LTS atual e layout do repositório, produz:

Matriz de breaking changes por serviço
Checklist de PRs ordenados (ferramentas → CI → Docker → runtime)
Comandos de verificação por estágio
Plano de rollback com tags de imagem e cronograma

Quando Invocar

Node 20 LTS se aproximando do fim de vida (EOL) e a plataforma exige a 24
Novo contratado descobriu que .nvmrc diz 18 enquanto o Docker usa 22
Falhas de build de add-on nativo após atualização da imagem base
Monorepo precisa de upgrade coordenado de múltiplos serviços

Entradas

Entrada	Por quê
Versão(ões) atual(is) do Node	Podem diferir por serviço legado
Versão alvo	`24.18.0` Active LTS
Contagem de repositórios	Monorepo vs muitos repositórios
Dependências nativas	`bcrypt`, `sharp`, `canvas` precisam de reconstrução
Plataforma de deploy	k8s, ECS, Fly, VM bare-metal

Saídas

Tabela de breaking changes (OpenSSL, fetch, test runner, ESM)
Sequência de PRs com responsáveis
Atualização da matriz de CI (node-version: [24.18.0])
Diff do Dockerfile FROM node:24.18.0-alpine
Checklist de soak em staging (24-48h)
Comandos de rollback

Guardrails

Atualize as ferramentas antes do código da aplicação - CI verde na nova versão do Node antes de mesclar mudanças de runtime.
Nunca misture versões do Node em um único artefato implantável.
Reconstrua módulos nativos - delete node_modules e regenere o lockfile se erros de ABI aparecerem.
Execute npm audit após reinstalar - a resolução pode mudar.
Faça soak em staging com shadow de tráfego de produção quando possível.
Mantenha a tag Docker anterior implantável por 7 dias.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Fase 1 - smoke test local na LTS alvo
fnm install 24.18.0 && fnm use 24.18.0
node -v   # v24.18.0
rm -rf node_modules
npm ci
npm run typecheck
npm test
npm run build
 
# Fase 2 - matriz de CI (trecho)
# .github/workflows/pr-checks.yml
# node-version: '24.18.0'
 
# Fase 3 - Docker
# FROM node:24.18.0-alpine
 
# Fase 4 - verificação em produção
kubectl set image deploy/orders-api orders-api=orders-api:node24-abc123
kubectl rollout status deploy/orders-api

Matriz de Breaking-Change (20 → 24)

Área	Risco	Ação
ESM padrão	`require()` em novos arquivos	Garanta `"type": "module"` ou sufixo `.cjs`
OpenSSL 3	Cifras TLS legadas	Teste HTTPS de saída para parceiros antigos
fetch estável	Duplicação do undici	Remova a dependência redundante `node-fetch`
Modelo de permissão	Uso raro em sandbox	Audite flags `--experimental-permission`
Add-ons nativos	Incompatibilidade de ABI	`npm rebuild` ou atualize a versão do pacote
Vitest/Jest	Configuração do pool	Atualize para versões que suportam Node 24
`url.parse`	Avisos de depreciação	Migre para o construtor `URL`

Exemplo de Trabalho: Ordem de PR de Monorepo

## Trem de PRs de Upgrade (Node 24.18.0)
 
PR1 [plataforma] - .nvmrc, engines, GitHub Actions node-version
PR2 [docker]  - Todas as linhas FROM do Dockerfile
PR3 [service-a] - Corrigir timeouts de teste expostos no 24
PR4 [service-b] - Reconstruir sharp após bump de ABI
PR5 [docs]    - CONTRIBUTING.md, runbooks
 
Soak: staging 48h, monitorar latência p95 e taxa de erro
Rollback: kubectl rollout undo deploy/orders-api

// package.json (raiz de cada workspace e serviço)
{
  "engines": {
    "node": "24.18.0",
    "npm": ">=10.0.0"
  }
}

# .nvmrc
24.18.0

Exemplos de Prompts

Usar Skill de Upgrade do Node:
- Atual: Node 20.18.0 em 4 serviços em monorepo de workspaces npm
- Alvo: 24.18.0
- Deps nativas: bcrypt em auth-api, sharp em media-worker
- Deploy: EKS com Helm
- Saída: Trem de PRs + matriz de breaking changes + rollback

FAQs

Big bang ou rolling por serviço?

Rolling por serviço em monorepos após PR1-2 serem aplicados em toda a plataforma. Menor risco do que atualizar todos os handlers na mesma hora.

Pular releases ímpares atuais?

Sempre mire apenas em Active LTS para produção. Releases ímpares são para adotantes iniciais, não para upgrades de frota.

Relacionados

Política de Release e LTS do Node.js - o que pode rodar em produção
Instalação e Gerenciamento de Versão - fnm/nvm
engines & engine-strict - impor localmente
Antes/Depois do Upgrade LTS Node 20→24 - estudo de caso

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.

O Que Esta Skill Faz

A partir da versão LTS atual e layout do repositório, produz:

Matriz de breaking changes por serviço
Checklist de PRs ordenados (ferramentas → CI → Docker → runtime)
Comandos de verificação por estágio
Plano de rollback com tags de imagem e cronograma

Quando Invocar

Node 20 LTS se aproximando do fim de vida (EOL) e a plataforma exige a 24
Novo contratado descobriu que .nvmrc diz 18 enquanto o Docker usa 22
Falhas de build de add-on nativo após atualização da imagem base
Monorepo precisa de upgrade coordenado de múltiplos serviços

Entradas

Entrada	Por quê
Versão(ões) atual(is) do Node	Podem diferir por serviço legado
Versão alvo	`24.18.0` Active LTS
Contagem de repositórios	Monorepo vs muitos repositórios
Dependências nativas	`bcrypt`, `sharp`, `canvas` precisam de reconstrução
Plataforma de deploy	k8s, ECS, Fly, VM bare-metal

Saídas

Tabela de breaking changes (OpenSSL, fetch, test runner, ESM)
Sequência de PRs com responsáveis
Atualização da matriz de CI (node-version: [24.18.0])
Diff do Dockerfile FROM node:24.18.0-alpine
Checklist de soak em staging (24-48h)
Comandos de rollback

Guardrails

Atualize as ferramentas antes do código da aplicação - CI verde na nova versão do Node antes de mesclar mudanças de runtime.
Nunca misture versões do Node em um único artefato implantável.
Reconstrua módulos nativos - delete node_modules e regenere o lockfile se erros de ABI aparecerem.
Execute npm audit após reinstalar - a resolução pode mudar.
Faça soak em staging com shadow de tráfego de produção quando possível.
Mantenha a tag Docker anterior implantável por 7 dias.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Fase 1 - smoke test local na LTS alvo
fnm install 24.18.0 && fnm use 24.18.0
node -v   # v24.18.0
rm -rf node_modules
npm ci
npm run typecheck
npm test
npm run build
 
# Fase 2 - matriz de CI (trecho)
# .github/workflows/pr-checks.yml
# node-version: '24.18.0'
 
# Fase 3 - Docker
# FROM node:24.18.0-alpine
 
# Fase 4 - verificação em produção
kubectl set image deploy/orders-api orders-api=orders-api:node24-abc123
kubectl rollout status deploy/orders-api

Matriz de Breaking-Change (20 → 24)

Área	Risco	Ação
ESM padrão	`require()` em novos arquivos	Garanta `"type": "module"` ou sufixo `.cjs`
OpenSSL 3	Cifras TLS legadas	Teste HTTPS de saída para parceiros antigos
fetch estável	Duplicação do undici	Remova a dependência redundante `node-fetch`
Modelo de permissão	Uso raro em sandbox	Audite flags `--experimental-permission`
Add-ons nativos	Incompatibilidade de ABI	`npm rebuild` ou atualize a versão do pacote
Vitest/Jest	Configuração do pool	Atualize para versões que suportam Node 24
`url.parse`	Avisos de depreciação	Migre para o construtor `URL`

Exemplo de Trabalho: Ordem de PR de Monorepo

## Trem de PRs de Upgrade (Node 24.18.0)
 
PR1 [plataforma] - .nvmrc, engines, GitHub Actions node-version
PR2 [docker]  - Todas as linhas FROM do Dockerfile
PR3 [service-a] - Corrigir timeouts de teste expostos no 24
PR4 [service-b] - Reconstruir sharp após bump de ABI
PR5 [docs]    - CONTRIBUTING.md, runbooks
 
Soak: staging 48h, monitorar latência p95 e taxa de erro
Rollback: kubectl rollout undo deploy/orders-api

// package.json (raiz de cada workspace e serviço)
{
  "engines": {
    "node": "24.18.0",
    "npm": ">=10.0.0"
  }
}

# .nvmrc
24.18.0

Exemplos de Prompts

Usar Skill de Upgrade do Node:
- Atual: Node 20.18.0 em 4 serviços em monorepo de workspaces npm
- Alvo: 24.18.0
- Deps nativas: bcrypt em auth-api, sharp em media-worker
- Deploy: EKS com Helm
- Saída: Trem de PRs + matriz de breaking changes + rollback

FAQs

Big bang ou rolling por serviço?

Rolling por serviço em monorepos após PR1-2 serem aplicados em toda a plataforma. Menor risco do que atualizar todos os handlers na mesma hora.

Pular releases ímpares atuais?

Sempre mire apenas em Active LTS para produção. Releases ímpares são para adotantes iniciais, não para upgrades de frota.

Relacionados

Política de Release e LTS do Node.js - o que pode rodar em produção
Instalação e Gerenciamento de Versão - fnm/nvm
engines & engine-strict - impor localmente
Antes/Depois do Upgrade LTS Node 20→24 - estudo de caso

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.

Skill de Upgrade do Node

Buscar na documentação

Skill de Upgrade do Node