nextjs-16-specialist

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js 16 Specialist

Next.js 16 专家指南

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.

此Skill可助你成为Next.js 16 + React 19.2 + TypeScript + Material-UI V7 + Firebase领域的专家。它提供了关于现代技术栈、关键破坏性变更、高级模式以及常见错误实用解决方案的深入知识。

Quando Usar Este Skill

何时使用此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

在以下场景使用此Skill：

创建采用完整技术栈（React + TypeScript + MUI + Firebase）的全新Next.js 16项目
从Next.js 15迁移至16（需处理强制破坏性变更）
在Next.js应用中基于Firebase实现认证功能
在Next.js App Router中集成Material-UI V7
解决async/await、Firebase、MUI或缓存相关的特定错误
借助Turbopack、Cache Components和文件系统缓存优化性能
实现TypedRoutes以保障导航的类型安全
使用Next.js DevTools MCP进行AI辅助调试
通过Layout Deduplication优化路由与导航
实现React 19.2的View Transitions和useEffectEvent
实现高级模式，如Error Boundaries和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)

组件	版本	用途
Next.js	16+	支持Server Components的全栈框架
React	19.2+	集成React Compiler的UI库
TypeScript	5.1+	完整的类型安全支持
Material-UI	V7	专业级组件库
Firebase	最新版	认证、Firestore、存储服务
Turbopack	稳定版	默认打包工具（速度提升2-5倍）

Estrutura do Conhecimento

知识结构

Este skill está organizado em 4 áreas principais:

此Skill主要分为4个核心领域：

1. Setup & Quickstart

1. 搭建与快速入门

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

从零开始创建项目
依赖的安装与配置
Firebase入门操作
生产前检查清单

2. Breaking Changes Críticos

2. 关键破坏性变更

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

强制异步API（
```
params
```
、
```
searchParams
```
）
```
middleware.ts
```
迁移至
```
proxy.ts
```
新的图片默认配置
Route Segment Configs迁移指南

3. Recursos Referenciais

3. 参考资源

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.

此Skill包含详细的参考文件，可按需查阅：

```
setup-guide-detailed.md
```
- 分步完整搭建指南
```
breaking-changes-reference.md
```
- Next.js 16所有变更内容
```
common-errors-solutions.md
```
- 40+错误及对应解决方案
```
advanced-patterns.md
```
- 专业级模式（认证、上传、测试）

可通过此Skill的References部分定位特定信息。

4. Padrões Avançados

4. 高级模式

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

带会话持久化的认证功能
结合Material-UI的Error Boundaries
基于Zod的校验
基于Storage的文件上传
基于Vitest和Testing Library的测试
在Vercel/Firebase Hosting部署

Como Usar Este Skill

如何使用此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
```

查阅：
```
setup-guide-detailed.md
```
→ 「从零创建项目」章节
执行：使用
```
create-next-app
```
命令创建项目
配置：按照步骤配置Firebase与Material-UI
验证：参考
```
setup-guide-detailed.md
```
中的生产前检查清单

Para Migrar do Next.js 15

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
```

阅读：
```
breaking-changes-reference.md
```
- 「升级指南」章节
执行：自动代码迁移命令：
```
npx @next/codemod@canary upgrade latest
```
检查：确保所有
```
params
```
/
```
searchParams
```
均使用
```
await
```
测试：通过
```
npx tsc --noEmit
```
验证TypeScript代码

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

查找：在
```
common-errors-solutions.md
```
中定位错误
分析：通过「❌ 症状」章节确定原因
应用：采用「✅ 正确方案」中的解决方法
测试：在本地提交前验证修改效果

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

查找：在
```
advanced-patterns.md
```
中定位对应模式
复制：示例代码（Auth Context、Error Boundary等）
适配：根据项目需求调整代码
测试：重点验证ProtectedRoute相关的认证功能

Dicas Rápidas

快速技巧

⚡ Turbopack (Default + File System Cache)

⚡ Turbopack（默认+文件系统缓存）

bash

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

bash

npm run dev  # 自动使用Turbopack
npm run build  # 比Webpack快2-5倍

Habilitar File System Caching (Beta)

启用文件系统缓存（Beta版）

next.config.ts

experimental: { turbopackFileSystemCacheForDev: true }

Restarts 3-5x mais rápidos! ✅

重启速度提升3-5倍！ ✅

undefined

undefined

📦 Cache Components (refresh, updateTag, revalidateTag)

📦 组件缓存（refresh, updateTag, revalidateTag）

typescript

'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

typescript

'use cache';  # 标记组件为可缓存
cacheTag('products');  # 标识缓存
revalidateTag('products', 'max');  # 通过SWR使缓存失效
updateTag('products');  # 读写一致性（即时更新）
refresh();  # 仅更新非缓存数据

🚀 Enhanced Routing (Automático)

🚀 增强型路由（自动生效）

typescript

undefined

typescript

undefined

Layout Deduplication - Zero config

Layout Deduplication - 无需配置

Layouts compartilhados baixados 1x só

共享布局仅下载一次

Economia: 50-80% de prefetch size ✅

优化效果：预加载体积减少50-80% ✅

Incremental Prefetching

增量预加载

Só prefetcha o que NÃO está em cache

仅预加载未缓存内容

Viewport-aware: cancela quando sai da tela

视口感知：离开视口时取消预加载

undefined

undefined

🔐 Firebase + Auth (Seguro)

🔐 Firebase + 认证（安全实践）

typescript

const app = getApps().length === 0 ? initializeApp(config) : getApps()[0];

typescript

const app = getApps().length === 0 ? initializeApp(config) : getApps()[0];

✅ Nunca reinicializa Firebase

✅ 避免重复初始化Firebase

undefined

undefined

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

⌛ Params现在为异步（强制要求！）

typescript

undefined

typescript

undefined

❌ ERRADO - Não compila no Next.js 16

❌ 错误写法 - Next.js 16无法编译

export default function Page({ params }) { }

✅ CORRETO - OBRIGATÓRIO

✅ 正确写法 - 强制要求

export default async function Page({ params }) { const { slug } = await params; }

undefined

export default async function Page({ params }) { const { slug } = await params; }

undefined

🔗 TypedRoutes (Type Safety para Links)

🔗 TypedRoutes（链接类型安全）

typescript

undefined

typescript

undefined

Habilitar em next.config.ts

在next.config.ts中启用

const nextConfig: NextConfig = { typedRoutes: true, // ✅ Detecta links inválidos no build };

const nextConfig: NextConfig = { typedRoutes: true, // ✅ 构建时检测无效链接 };

Uso

使用示例

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

<Link href="/about" /> // ✅ 验证通过 <Link href="/aboot" /> // ❌ 检测到类型错误 router.push(`/blog/${slug}`); // ✅ 模板字符串验证通过 ```

🤖 Next.js DevTools MCP (IA Integrada)

🤖 Next.js DevTools MCP（集成AI）

json

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

json

// 项目根目录下的.mcp.json文件
{
  "mcpServers": {
    "next-devtools": {
      "command": "npx",
      "args": ["-y", "next-devtools-mcp@latest"]
    }
  }
}

Claude Code agora vê:

Claude Code可实时查看：

- Erros em tempo real

- 实时错误

- Estrutura do projeto

- 项目结构

- Logs do dev server

- 开发服务器日志

- Metadados de páginas

- 页面元数据

undefined

undefined

✨ React 19.2 (View Transitions + useEffectEvent)

✨ React 19.2（View Transitions + useEffectEvent）

typescript

undefined

typescript

undefined

View Transitions (animações suaves)

View Transitions（平滑动画）

useEffectEvent (lógica não-reativa)

useEffectEvent（非响应式逻辑）

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

undefined

const logView = useEffectEvent(() => { analytics.track('view', { userId }); // 始终为最新值 }); useEffect(() => logView(), [productId]); // 仅在productId变化时重新执行

undefined

🎨 Material-UI V7 (Sempre AppRouterCacheProvider)

🎨 Material-UI V7（必须使用AppRouterCacheProvider）

typescript

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

typescript

<AppRouterCacheProvider>  {# 必须放在最外层 #}
  <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

Node.js: 20.9.0+（不再支持18版本）
npm: 推荐9.x+
TypeScript: 5.1.0+（从4.9版本升级）
React: 19.2+（集成稳定版React Compiler）
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

已安装Node.js 20.9+
若从Next.js 15迁移，已阅读
```
breaking-changes-reference.md
```
全新项目已遵循
```
setup-guide-detailed.md
```
的步骤
已配置包含Firebase变量的
```
.env.local
```
文件
已在本地测试认证功能
遇到错误时已查阅
```
common-errors-solutions.md
```
已在
```
tsconfig.json
```
中启用
```
strict: true
```
已运行
```
npx next typegen
```
生成自动类型

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
```

全新项目：查看
```
references/setup-guide-detailed.md
```

迁移场景：查看

references/breaking-changes-reference.md

错误排查：查看
```
references/common-errors-solutions.md
```
高级功能：查看
```
references/advanced-patterns.md
```

🚀 Features do Next.js 16

🚀 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!)

组件缓存（use cache, refresh, updateTag）：查看
```
features/cache-components-deep-dive.md
```
Turbopack + 文件系统缓存：查看
```
features/turbopack-masterclass.md
```
增强型路由与导航：查看
```
features/enhanced-routing-navigation.md
```
（新增！）
TypedRoutes（类型安全）：查看
```
features/typed-routes-complete-guide.md
```
（新增！）
Next.js DevTools MCP（AI集成）：查看
```
features/nextjs-devtools-mcp-guide.md
```
（新增！）

⚛️ React 19.2 Features

⚛️ React 19.2新特性

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

View Transitions、useEffectEvent、Activity：查看
```
features/react-19-2-new-features.md
```

最后更新：2025年11月（Next.js 16.0.0 - 100%覆盖） 兼容性：Next.js 16+ 与 React 19.2+ 状态：可用于生产环境

🎉 Novidades Recentes (Novembro 2025)

🎉 近期更新（2025年11月）

✅ 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! 🚀

✅ TypedRoutes指南 - 完整的导航类型安全方案
✅ Next.js DevTools MCP - 集成Claude Code的AI辅助调试
✅ 增强型路由与导航 - Layout Deduplication + 增量预加载
✅ refresh() API - 针对非缓存数据的全新缓存API
✅ View Transitions - React 19.2的声明式动画
✅ useEffectEvent - 用于Effect中非响应式逻辑的Hook
✅ Turbopack文件系统缓存 - 重启速度提升3-5倍

总计：3份新指南 + 4份更新指南 + Next.js 16 100%覆盖！ 🚀