next-upgrade

Visão geral da skill next-upgrade

O que a next-upgrade faz

A skill next-upgrade ajuda um agente a atualizar um projeto Next.js real para uma versão major mais recente usando os guias oficiais de migração e codemods, em vez de tentar adivinhar com base na memória. O trabalho dela é prático: detectar a versão atual de next no seu app, mapear o caminho de upgrade mais seguro, aplicar primeiro os codemods corretos, depois atualizar as dependências e revisar breaking changes que ainda exigem edições manuais.

Para quem a skill next-upgrade é indicada

Esta skill é mais indicada para desenvolvedores que mantêm uma base de código Next.js existente e querem que um assistente de IA planeje ou execute um upgrade com menos desvio em relação à orientação oficial. Ela é especialmente útil quando:

• seu projeto está mais de uma versão major defasado
• você quer um plano de upgrade com contexto do repositório, e não um checklist genérico
• você precisa de ajuda para identificar codemods específicos por versão e alinhar dependências
• você quer suporte dentro de um fluxo de Code Editing, não apenas um resumo no navegador

O trabalho real que ela resolve

A maioria dos usuários não precisa de “informações sobre upgrades do Next.js”. O que precisam é sair de um app que funciona hoje para uma versão mais nova do Next.js sem quebrar roteamento, compatibilidade com React, output de build ou APIs de runtime. A next-upgrade foi pensada para exatamente esse caminho de decisão e execução.

O que diferencia a next-upgrade de um prompt comum

Um prompt simples pode sugerir conselhos amplos de upgrade. A next-upgrade é mais específica e mais útil porque se organiza em torno de:

• ler primeiro o seu package.json
• consultar os guias oficiais de upgrade do Next.js para a versão de destino
• tratar saltos entre versões major de forma incremental
• priorizar codemods oficiais antes de edições manuais
• atualizar next, react e react-dom em conjunto e da forma correta

O que ela não faz por você

A skill não elimina a necessidade de validação. Ela pode orientar mudanças no código e atualizações de dependências, mas você ainda precisa rodar seu app, testes, linting e checagens de build. Ela também não substitui conhecimento específico de framework em setups muito customizados, como monorepos, integrações incomuns com bundlers ou comportamentos de servidor/runtime fortemente modificados.

Como usar a skill next-upgrade

Contexto de instalação da next-upgrade

Instale a skill no seu ambiente de IA para programação para que ela possa ser invocada enquanto você trabalha dentro do repositório que quer atualizar. Um padrão comum de instalação é:

npx skills add https://github.com/vercel-labs/next-skills --skill next-upgrade

Se o seu ambiente já expõe skills do GitHub a partir de vercel-labs/next-skills, talvez você só precise chamar next-upgrade diretamente.

Como invocar a next-upgrade na prática

O repositório indica uma dica de argumento [target-version], então o uso mais limpo é informar explicitamente a versão desejada, por exemplo:

• Use next-upgrade for Next.js 16
• Run next-upgrade targeting v15
• Apply the next-upgrade skill to move this app from 13 to 15 incrementally

Se você ainda não souber a versão de destino, peça primeiro um plano:

• Use next-upgrade to inspect this repo and recommend the safest target version

Quais entradas a skill precisa

A next-upgrade funciona melhor quando o agente consegue inspecionar:

• package.json
• lockfile como package-lock.json, pnpm-lock.yaml ou yarn.lock
• configuração de workspace se o app estiver em um monorepo
• a estrutura de diretórios do app, especialmente se você usa app/ ou pages/
• comandos de CI ou build usados para validar o upgrade

Entrada mínima útil:

• versão atual do Next.js
• gerenciador de pacotes
• versão de destino desejada
• se você quer apenas planejamento ou edições reais no código

Como transformar um objetivo vago em um bom prompt para next-upgrade

Prompt fraco:

• Upgrade my app

Prompt melhor:

• Use next-upgrade to inspect package.json, determine the current Next.js version, upgrade this project to Next.js 15 using official migration guides, run the relevant @next/codemod transforms first, then update next/react/react-dom together and summarize any manual follow-up changes.

Melhor prompt quando seu repositório não é trivial:

• Use next-upgrade for Code Editing on this monorepo app in apps/web. Read apps/web/package.json, identify the current next/react versions, plan the required incremental major upgrades to reach Next.js 16, apply official codemods where relevant, update dependencies with pnpm-compatible commands, and leave a checklist of manual verification steps for build, routing, and runtime APIs.

Esse nível extra de especificidade melhora o resultado porque a skill em si é enxuta; o seu prompt fornece os limites do repositório, o gerenciador de pacotes e o escopo de execução.

Fluxo recomendado da next-upgrade antes de editar arquivos

Um fluxo confiável de next-upgrade usage é:

1. inspecionar package.json e as versões atuais das dependências
2. escolher a versão de destino
3. buscar o guia oficial de upgrade do Next.js para cada etapa major envolvida
4. rodar os codemods antes da limpeza manual
5. atualizar next, react e react-dom
6. executar lint, typecheck, testes e build de produção
7. corrigir os breaking changes restantes apontados pelo guia ou por erros em runtime

Se você está várias versões atrás, não salte no escuro. Peça ao agente para tratar 13 -> 14 -> 15 -> 16 como etapas de upgrade separadas.

Arquivo do repositório para ler primeiro

Comece por skills/next-upgrade/SKILL.md no repositório upstream:

• https://github.com/vercel-labs/next-skills/tree/main/skills/next-upgrade

É uma skill curta, então não há muitos arquivos de suporte para inspecionar. O principal valor está no fluxo codificado em SKILL.md: detectar a versão, buscar a documentação oficial, atualizar incrementalmente, rodar codemods primeiro e só depois atualizar as dependências.

Documentação oficial da qual esta skill depende

A skill aponta explicitamente para recursos oficiais de upgrade do Next.js, incluindo:

• codemods: https://nextjs.org/docs/app/guides/upgrading/codemods
• guias por versão, como:
  • https://nextjs.org/docs/app/guides/upgrading/version-16
  • https://nextjs.org/docs/app/guides/upgrading/version-15
  • https://nextjs.org/docs/app/guides/upgrading/version-14

Isso importa na hora de decidir adotar a skill: a next-upgrade só é tão boa quanto a disposição do agente para buscar e seguir esses guias, em vez de confiar em conhecimento desatualizado sobre o framework.

Na next-upgrade, codemods vêm antes, não depois

Uma das partes mais fortes do next-upgrade guide é a sequência de execução. Ele orienta o agente a rodar os codemods oficiais cedo no processo:
npx @next/codemod@latest <transform> <path>

Exemplos destacados pela skill incluem:

• next-async-request-api
• next-request-geo-ip
• next-dynamic-access-named-export

Essa ordem é importante porque os codemods costumam lidar com breaking changes repetitivos com mais rapidez e segurança do que editar tudo manualmente depois de subir as dependências.

Atualizações de dependências que vale pedir explicitamente

Ao usar a next-upgrade, peça ao agente para atualizar as peer dependencies em conjunto. A skill enfatiza especificamente este padrão:
npm install next@latest react@latest react-dom@latest

Mesmo que você use pnpm ou yarn, o ponto continua o mesmo: trate next, react e react-dom como um conjunto coordenado, salvo se o guia oficial disser o contrário.

next-upgrade para Code Editing

Para Code Editing, a next-upgrade é mais útil quando você permite que o agente tanto inspecione quanto modifique arquivos, e não apenas produza um plano. Boas tarefas incluem:

• atualizar intervalos de versão de dependências em package.json
• aplicar comandos de codemod
• alterar APIs afetadas por breaking changes
• deixar comentários inline ou um resumo da migração para revisão manual

Ela é menos útil se o seu ambiente não consegue acessar os arquivos do repositório ou a documentação externa, porque a vantagem da skill vem justamente da combinação entre inspeção do repo e consulta aos guias oficiais.

Restrições práticas e tradeoffs

Use a next-upgrade quando você quiser um caminho disciplinado, mas espere algumas limitações:

• ela não codifica localmente todas as nuances de cada versão; espera consultar os guias em tempo real
• funciona melhor em apps Next.js padrão, não em infra muito customizada
• ela não oferece automação de testes específica do projeto embutida
• pode exigir prompts mais detalhados para monorepos, subapps ou arquivos de pacote fora da raiz

Em resumo, a skill reduz o achismo, mas o seu prompt ainda precisa definir o escopo com clareza.

FAQ da skill next-upgrade

A next-upgrade é melhor do que um prompt genérico de upgrade?

Em geral, sim, se você quer um processo de upgrade reproduzível. Um prompt genérico pode gerar conselhos plausíveis, porém desatualizados. A next-upgrade se ancora nos guias oficiais de migração, nos codemods e na detecção de versão a partir dos arquivos do seu projeto.

A skill next-upgrade é amigável para iniciantes?

Sim, com uma ressalva: iniciantes devem usá-la primeiro em modo de planejamento. Peça:

• detecção da versão atual
• recomendação de versão de destino
• codemods a executar
• mudanças manuais prováveis
• checklist de validação

Isso deixa a saída mais fácil de revisar antes de permitir edições.

Preciso saber a versão de destino antes?

Não. Você pode pedir para a next-upgrade inspecionar o repositório e recomendar a versão de destino mais segura. Mas, se você já sabe que precisa de uma versão específica por motivos de plataforma ou dependências, informar o alvo desde o início gera um plano mais limpo.

Quando eu não devo usar a next-upgrade?

Ignore a next-upgrade se:

• você está criando um app novo, e não atualizando um existente
• seu problema não tem relação com migração de versão
• sua stack depende de internals customizados não cobertos pela documentação oficial
• você só precisa de um comando de uma linha e já sabe exatamente o caminho de versão

A next-upgrade consegue lidar com saltos de várias versões?

Sim, mas de forma incremental. A skill favorece explicitamente upgrades major em etapas, em vez de um salto único e cego. Se o seu app está muito defasado, peça um plano em fases com checkpoints após cada versão major.

Ela funciona só para projetos com app router?

Não, mas os guias oficiais que ela consulta podem enfatizar padrões mais novos do Next.js. Se sua base ainda usa convenções antigas, peça ao agente para identificar quais partes do guia se aplicam e quais não, antes de fazer edições.

Como melhorar a skill next-upgrade

Dê à next-upgrade limites de repositório mais claros

A forma mais rápida de melhorar os resultados é dizer ao agente exatamente onde o app Next.js está. Em um monorepo, especifique:

• caminho do app, como apps/web
• gerenciador de pacotes
• ferramenta de workspace
• se as edições devem ficar restritas àquele app

Sem isso, a skill pode inspecionar o package.json errado ou sugerir comandos no nível incorreto.

Peça uma saída em duas fases

Um padrão forte é:

1. apenas o plano
2. executar as edições

Exemplo:

• Use next-upgrade to first produce an upgrade plan with required codemods and risks. After I approve it, apply the changes.

Isso reduz edições amplas acidentais e torna a skill mais confiável em codebases de produção.

Forneça critérios de validação mais fortes

Não peça apenas para “atualizar com sucesso”. Peça ao agente para validar com comandos concretos, como:

• install
• lint
• typecheck
• unit tests
• production build

Isso melhora o next-upgrade usage, porque o agente pode otimizar para um repositório passando em todas as verificações, e não apenas para linhas de dependência atualizadas.

Nomeie os modos de falha que mais importam para você

Se sua prioridade é evitar regressões específicas, deixe isso explícito. Por exemplo:

• Prioritize route behavior and middleware compatibility
• Watch for request API changes introduced in newer Next.js versions
• Do not migrate unrelated code while applying next-upgrade

Essas restrições produzem edições melhores do que um pedido amplo como “faz funcionar”.

Peça a justificativa da seleção de codemods

Um prompt útil de melhoria é:

• List which @next/codemod transforms apply to this repo and why before running them

Isso ajuda você a revisar se o agente está relacionando os transforms aos padrões reais do código, em vez de rodar codemods indiscriminadamente.

Modos de falha comuns com a next-upgrade

Padrões típicos de resultados fracos incluem:

• atualizar dependências sem antes verificar a versão atual
• pular versões major intermediárias
• editar manualmente antes de revisar os codemods
• ignorar o alinhamento entre react e react-dom
• presumir que o package.json da raiz é o pacote do app em um monorepo

Se você vir esses sinais, pare e peça um plano versão por versão.

Como iterar depois da primeira saída

Depois da primeira passada, peça uma segunda rodada mais focada no que falhou:

• Re-run next-upgrade analysis based on these build errors
• Compare the remaining errors against the official v15 guide
• Propose the smallest manual edits still needed after codemods

Isso é melhor do que recomeçar do zero, porque a skill foi desenhada em torno de etapas de migração, não de perfeição em uma única tentativa.

Melhor padrão de prompt para resultados de maior qualidade com next-upgrade

Um template compacto e de alto sinal:

Use next-upgrade on <path>. Detect the current Next.js version from package.json, determine the correct incremental upgrade path to <target-version>, fetch the official migration guides for each step, identify and run the applicable @next/codemod transforms first, then update next/react/react-dom together. After edits, summarize breaking changes addressed, remaining manual follow-ups, and the exact verification commands I should run.

Esse prompt dá à next-upgrade skill estrutura suficiente para produzir uma saída materialmente melhor do que um pedido genérico de Code Editing.