Next.js 16 Specialist

Overview

Este skill transforma você em um especialista em Next.js 16 com React 19.2, TypeScript, Material-UI V7 e Firebase. Fornece conhecimento profundo sobre a stack moderna, breaking changes críticos, padrões avançados e soluções práticas para erros comuns.

Quando Usar Este Skill

Use este skill quando:

Criar novo projeto Next.js 16 com stack completa (React + TypeScript + MUI + Firebase)
Migrar de Next.js 15 para 16 (breaking changes obrigatórios)
Implementar autenticação com Firebase em aplicações Next.js
Trabalhar com Material-UI V7 integrado ao Next.js App Router
Resolver erros específicos de async/await, Firebase, MUI ou caching
Otimizar performance com Turbopack, Cache Components e File System Caching
Implementar TypedRoutes para type safety em navegação
Usar Next.js DevTools MCP para debugging assistido por IA
Otimizar routing e navigation com Layout Deduplication
Implementar View Transitions e useEffectEvent do React 19.2
Implementar padrões avançados como Error Boundaries e Protected Routes

Stack Completo

Componente	Versão	Propósito
Next.js	16+	Framework full-stack com Server Components
React	19.2+	UI library com React Compiler
TypeScript	5.1+	Type safety completo
Material-UI	V7	Component library profissional
Firebase	Latest	Auth, Firestore, Storage
Turbopack	Stable	Bundler padrão (2-5x mais rápido)

Estrutura do Conhecimento

Este skill está organizado em 4 áreas principais:

1. Setup & Quickstart

Criação de projeto do zero
Instalação e configuração de dependências
Primeiros passos com Firebase
Checklist pré-produção

2. Breaking Changes Críticos

APIs assíncronas obrigatórias (params, searchParams)
Mudança de middleware.ts → proxy.ts
Novos defaults de imagem
Migrações de Route Segment Configs

3. Recursos Referenciais

Este skill inclui arquivos de referência detalhada que devem ser consultados conforme necessário:

setup-guide-detailed.md - Setup completo passo-a-passo
breaking-changes-reference.md - Todas as mudanças do Next.js 16
common-errors-solutions.md - 40+ erros e soluções
advanced-patterns.md - Padrões profissionais (Auth, Upload, Testing)

Use a seção References deste skill para localizar informações específicas.

4. Padrões Avançados

Autenticação com persistência de sessão
Error Boundaries com Material-UI
Validação com Zod
Upload de arquivos com Storage
Testes com Vitest e Testing Library
Deployment em Vercel/Firebase Hosting

Como Usar Este Skill

Para um Novo Projeto

Consulte: setup-guide-detailed.md → Seção "Criando o Projeto do Zero"
Execute: Comandos de criação do projeto com create-next-app
Configure: Firebase, Material-UI seguindo os passos
Valide: Checklist pré-produção em setup-guide-detailed.md

Para Migrar do Next.js 15

Leia: breaking-changes-reference.md - Seção "Guia de Atualização"
Execute: Codemod automático: npx @next/codemod@canary upgrade latest
Verifique: Todos os params/searchParams agora precisam de await
Teste: Seu código TypeScript com npx tsc --noEmit

Para Resolver Erros

Procure: O erro em common-errors-solutions.md
Estude: Seção "❌ Sintoma" para identificar causa
Aplique: Solução em "✅ CORRETO"
Teste: Mudanças localmente antes de commit

Para Implementar Recursos Avançados

Procure: O padrão em advanced-patterns.md
Copie: Código de exemplo (Auth Context, Error Boundary, etc.)
Adapte: Para seu projeto específico
Teste: Especialmente autenticação com ProtectedRoute

Dicas Rápidas

⚡ Turbopack (Default + File System Cache)

npm run dev  # Usa Turbopack automaticamente
npm run build  # 2-5x mais rápido que Webpack

# Habilitar File System Caching (Beta)
# next.config.ts
experimental: { turbopackFileSystemCacheForDev: true }
# Restarts 3-5x mais rápidos! ✅

📦 Cache Components (refresh, updateTag, revalidateTag)

'use cache';  # Marcar componente como cacheado
cacheTag('products');  # Identificar cache
revalidateTag('products', 'max');  # Invalidar com SWR
updateTag('products');  # Read-your-writes (imediato)
refresh();  # Atualizar dados não-cacheados apenas

🚀 Enhanced Routing (Automático)

# Layout Deduplication - Zero config
# Layouts compartilhados baixados 1x só
# Economia: 50-80% de prefetch size ✅

# Incremental Prefetching
# Só prefetcha o que NÃO está em cache
# Viewport-aware: cancela quando sai da tela

🔐 Firebase + Auth (Seguro)

const app = getApps().length === 0 ? initializeApp(config) : getApps()[0];
# ✅ Nunca reinicializa Firebase

⌛ Params Agora são Async (Obrigatório!)

# ❌ ERRADO - Não compila no Next.js 16
export default function Page({ params }) { }

# ✅ CORRETO - OBRIGATÓRIO
export default async function Page({ params }) {
  const { slug } = await params;
}

🔗 TypedRoutes (Type Safety para Links)

# Habilitar em next.config.ts
const nextConfig: NextConfig = {
  typedRoutes: true,  // ✅ Detecta links inválidos no build
};

# Uso
<Link href="/about" />  // ✅ Validado
<Link href="/aboot" />  // ❌ Type error detectado
router.push(`/blog/${slug}`);  // ✅ Template literals validados

🤖 Next.js DevTools MCP (IA Integrada)

// .mcp.json na raiz do projeto
{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

# Claude Code agora vê:
# - Erros em tempo real
# - Estrutura do projeto
# - Logs do dev server
# - Metadados de páginas

✨ React 19.2 (View Transitions + useEffectEvent)

# View Transitions (animações suaves)
<ViewTransition name="product-1">
  <ProductCard />
</ViewTransition>

# useEffectEvent (lógica não-reativa)
const logView = useEffectEvent(() => {
  analytics.track('view', { userId }); // Sempre atualizado
});
useEffect(() => logView(), [productId]); // Só re-executa com productId

🎨 Material-UI V7 (Sempre AppRouterCacheProvider)

<AppRouterCacheProvider>  {# OBRIGATÓRIO primeiro #}
  <ThemeProvider theme={theme}>
    {children}
  </ThemeProvider>
</AppRouterCacheProvider>

Tecnologias & Versões

Node.js: 20.9.0+ (18 não é mais suportado)
npm: 9.x+ recomendado
TypeScript: 5.1.0+ (aumentado de 4.9)
React: 19.2+ (com React Compiler estável)
Next.js: 16.0.0+
Material-UI: 7.x

Checklist de Início

Node.js 20.9+ instalado
Ler breaking-changes-reference.md se migrando de Next.js 15
Seguir setup-guide-detailed.md para novo projeto
Configurar .env.local com variáveis Firebase
Testar autenticação localmente
Verificar common-errors-solutions.md ao encontrar erros
Ativar strict: true em tsconfig.json
Rodar npx next typegen para tipos automáticos

Próximos Passos

📚 Guias Essenciais

Para novo projeto: Veja references/setup-guide-detailed.md
Para migração: Veja references/breaking-changes-reference.md
Para erros: Veja references/common-errors-solutions.md
Para avançado: Veja references/advanced-patterns.md

🚀 Features do Next.js 16

Cache Components (use cache, refresh, updateTag): Veja features/cache-components-deep-dive.md
Turbopack + File System Caching: Veja features/turbopack-masterclass.md
Enhanced Routing & Navigation: Veja features/enhanced-routing-navigation.md (NOVO!)
TypedRoutes (Type Safety): Veja features/typed-routes-complete-guide.md (NOVO!)
Next.js DevTools MCP (IA Integration): Veja features/nextjs-devtools-mcp-guide.md (NOVO!)

⚛️ React 19.2 Features

View Transitions, useEffectEvent, Activity: Veja features/react-19-2-new-features.md

Última Atualização: Novembro 2025 (Next.js 16.0.0 - Cobertura 100% Completa) Compatibilidade: Next.js 16+ com React 19.2+ Status: Estável para produção

🎉 Novidades Recentes (Novembro 2025)

✅ TypedRoutes Guide - Type safety completo para navegação
✅ Next.js DevTools MCP - Debugging assistido por IA com Claude Code
✅ Enhanced Routing & Navigation - Layout Deduplication + Incremental Prefetching
✅ refresh() API - Nova API de cache para dados não-cacheados
✅ View Transitions - Animações declarativas do React 19.2
✅ useEffectEvent - Hook para lógica não-reativa em Effects
✅ Turbopack File System Caching - Restarts 3-5x mais rápidos

Total: 3 novos guias + 4 guias atualizados + cobertura 100% do Next.js 16! 🚀

nextjs-16-specialist