Capítulo 95 de 456
Guia de upgrade de Next.js 15 para 16 — a versão que estabiliza o Turbopack como padrão, remove totalmente o acesso síncrono às Async Request APIs, renomeia middleware para proxy, estabiliza cacheLife/cacheTag/updateTag, e recomenda um fluxo assistido por agente de IA.
AGENTS.md (docs versionadas em node_modules/next/dist/docs/), seguir o guia de upgrade como fonte de verdade, rodar o codemod, explicar o plano, e verificar em runtime com a skill next-dev-loop (Next.js 16.3+ com Turbopack).npx @next/codemod@canary agents-md: gera/atualiza AGENTS.md com bloco gerenciado apontando para docs versionadas, evitando que o agente use conhecimento desatualizado sobre a API.upgrade latest: atualiza config do Turbopack, migra next lint→ESLint CLI, migra middleware→proxy, remove prefixo unstable_, remove experimental_ppr. NÃO roda o codemod de Async Request APIs — rodar next-async-request-api separadamente se ainda usa acesso síncrono legado da v15.next dev e next build usam Turbopack sem flag; --turbopack/--turbo não são mais necessários. Se houver config webpack customizada, next build falha por padrão (proteção contra misconfiguration) — opções: --turbopack (ignora webpack config), migrar config para Turbopack, ou --webpack para manter Webpack.turbopack config no top-level: experimental.turbopack saiu do experimental e virou turbopack na raiz do next.config.turbopack.resolveAlias: equivalente ao resolve.fallback do Webpack para silenciar módulos Node.js nativos (fs) em bundles client-side, e para lidar com o prefixo legado ~ do Sass (não suportado pelo Turbopack).experimental.turbopackFileSystemCacheForDev/...ForBuild.cookies(), headers(), draftMode(), params, searchParams (e props de opengraph-image/twitter-image/icon/apple-icon) só podem ser acessadas de forma assíncrona — a compatibilidade temporária da v15 (UnsafeUnwrapped*) acabou.npx next typegen: gera helpers PageProps, LayoutProps, RouteContext para migração type-safe para params/searchParams assíncronos (disponível desde 15.5).revalidateTag exige segundo argumento: agora precisa de um perfil cacheLife (ex. revalidateTag('posts', 'max')); forma de um argumento só é deprecated e gera erro de TypeScript.updateTag: nova API exclusiva de Server Actions com semântica read-your-writes — expira e refresca dados na mesma requisição, diferente de revalidateTag (stale-while-revalidate).refresh: refresca o client router a partir de uma Server Action, sem necessariamente invalidar cache.cacheLife/cacheTag estáveis: prefixo unstable_ não é mais necessário.middleware → proxy: nome de arquivo e export deprecados; proxy roda só em runtime nodejs (não suporta edge — quem precisa de edge deve continuar usando middleware por enquanto); flags de config renomeadas (skipMiddlewareUrlNormalize → skipProxyUrlNormalize).cacheComponents: a flag experimental experimental_ppr/experimental.ppr foi removida; PPR agora se habilita com cacheComponents: true, com comportamento diferente das canaries da v15.next/image: query strings em imagens locais: agora exigem images.localPatterns.search configurado explicitamente, prevenindo ataques de enumeração.npx @next/codemod@canary upgrade latest
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start"
}
}
--turbopack, já que é o padrão na v16.const nextConfig: NextConfig = {
turbopack: {
resolveAlias: {
fs: { browser: './empty.ts' },
},
},
}
Module not found: Can't resolve 'fs' no client bundle via turbopack.resolveAlias (equivalente ao resolve.fallback do Webpack).'use server'
import { updateTag } from 'next/cache'
export async function updateUserProfile(userId: string, profile: Profile) {
await db.users.update(userId, profile)
updateTag(`user-${userId}`) // usuário vê a mudança imediatamente
}
updateTag para read-your-writes imediato, em contraste com revalidateTag('posts', 'max') que aceita staleness temporária.mv middleware.ts proxy.ts
export function proxy(request: Request) {}
middleware.| Requisito | Mudança |
|---|---|
| Node.js | Mínimo 20.9.0 (LTS); Node 18 não suportado |
| TypeScript | Mínimo 5.1.0 |
| Browsers | Chrome/Edge/Firefox 111+, Safari 16.4+ |
O que o codemod upgrade faz | Cobertura |
|---|---|
Atualiza next.config.js pra nova config turbopack | Sim |
Migra next lint → ESLint CLI | Sim |
Migra middleware → proxy | Sim |
Remove prefixo unstable_ de APIs estabilizadas | Sim |
Remove experimental_ppr do Route Segment Config | Sim |
Migra acesso síncrono legado a cookies()/params/etc. | Não — rodar next-async-request-api à parte |
--turbopack/--turbo nos scripts após a v16: redundante, já que é o padrão; não é erro, mas é ruído.next build com config webpack customizada sem decidir explicitamente o caminho: falha por padrão — escolher entre --turbopack (ignora webpack), migrar config, ou --webpack (mantém Webpack).~pacote/arquivo: Turbopack não suporta o prefixo ~; usar import direto (@import 'bootstrap/dist/css/bootstrap.min.css') ou resolveAlias: { '~*': '*' }.revalidateTag('tag') de um argumento só ainda funciona: agora requer perfil cacheLife como segundo argumento.middleware com runtime edge esperando que proxy seja um rename direto: proxy só roda em nodejs; quem depende de edge deve manter middleware até orientação futura.AGENTS.md apontando para docs versionadas — evita o agente usar conhecimento desatualizado sobre APIs que mudaram.upgrade latest cobre a maior parte mecânica, mas não migra acesso síncrono legado — rode next-async-request-api separadamente se necessário.revalidateTag (agora com perfil obrigatório), updateTag (read-your-writes), refresh (refresh de router sem invalidar cache).proxy substitui middleware mas com restrição de runtime (nodejs apenas) — não é drop-in replacement para quem usa edge.agents-md, upgrade, next-async-request-api, middleware-to-proxy cobrem partes específicas desta migração.cacheComponents (novo caminho de PPR) é a materialização prática dessa filosofia.proxy.js é o mesmo arquivo referenciado lá, agora com nome atualizado.