nextjs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js Community Next.js 16 App Router Best Practices

Next.js 社区 Next.js 16 App Router 最佳实践

Comprehensive performance optimization guide for Next.js 16 App Router applications, maintained by the Next.js Community. Contains 40 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

由 Next.js 社区维护的 Next.js 16 App Router 应用性能优化综合指南。包含 8 个类别共 40 条规则，按影响优先级排序，可指导自动化重构和代码生成。

When to Apply

适用场景

Reference these guidelines when:

Writing new Next.js 16 App Router code
Configuring caching strategies with 'use cache' directive
Implementing server components and data fetching
Setting up routing with parallel and intercepting routes
Creating server actions for form handling and mutations

以下场景可参考本指南：

编写新的 Next.js 16 App Router 代码
使用 'use cache' 指令配置缓存策略
实现服务端组件（Server Components）和数据获取逻辑
设置并行路由与拦截路由
创建用于表单处理和数据变更的 Server Actions

Rule Categories by Priority

按优先级划分的规则类别


build-
cache-
server-
route-
action-
stream-
meta-
client-

Priority	Category	Impact	Prefix
1	Build & Bundle Optimization	CRITICAL	`build-`
2	Caching Strategy	CRITICAL	`cache-`
3	Server Components & Data Fetching	HIGH	`server-`
4	Routing & Navigation	HIGH	`route-`
5	Server Actions & Mutations	MEDIUM-HIGH	`action-`
6	Streaming & Loading States	MEDIUM	`stream-`
7	Metadata & SEO	MEDIUM	`meta-`
8	Client Components	LOW-MEDIUM	`client-`


build-
cache-
server-
route-
action-
stream-
meta-
client-

优先级	类别	影响程度	前缀
1	构建与打包优化	关键（CRITICAL）	`build-`
2	缓存策略	关键（CRITICAL）	`cache-`
3	服务端组件与数据获取	高（HIGH）	`server-`
4	路由与导航	高（HIGH）	`route-`
5	Server Actions 与数据变更	中高（MEDIUM-HIGH）	`action-`
6	流式处理与加载状态	中（MEDIUM）	`stream-`
7	元数据与 SEO	中（MEDIUM）	`meta-`
8	客户端组件	中低（LOW-MEDIUM）	`client-`

Quick Reference

快速参考

1. Build & Bundle Optimization (CRITICAL)

1. 构建与打包优化（关键）

```
build-optimize-package-imports
```
- Configure optimizePackageImports for Icon Libraries
```
build-dynamic-imports
```
- Use Dynamic Imports for Heavy Components
```
build-barrel-files
```
- Avoid Barrel File Imports in App Router
```
build-turbopack-config
```
- Enable Turbopack File System Caching
```
build-external-packages
```
- Configure Server External Packages for Node Dependencies

```
build-optimize-package-imports
```
- 为图标库配置 optimizePackageImports
```
build-dynamic-imports
```
- 对大型组件使用动态导入
```
build-barrel-files
```
- 在 App Router 中避免桶文件导入
```
build-turbopack-config
```
- 启用 Turbopack 文件系统缓存
```
build-external-packages
```
- 为 Node 依赖配置服务端外部包

2. Caching Strategy (CRITICAL)

2. 缓存策略（关键）

```
cache-use-cache-directive
```
- Use the 'use cache' Directive for Explicit Caching
```
cache-revalidate-tag
```
- Use revalidateTag with cacheLife Profiles
```
cache-fetch-options
```
- Configure Fetch Cache Options Correctly
```
cache-revalidate-path
```
- Use revalidatePath for Route-Level Cache Invalidation
```
cache-react-cache
```
- Use React cache() for Request Deduplication
```
cache-segment-config
```
- Configure Route Segment Caching with Exports

```
cache-use-cache-directive
```
- 使用 'use cache' 指令进行显式缓存
```
cache-revalidate-tag
```
- 结合 cacheLife 配置文件使用 revalidateTag
```
cache-fetch-options
```
- 正确配置 Fetch 缓存选项
```
cache-revalidate-path
```
- 使用 revalidatePath 进行路由级缓存失效
```
cache-react-cache
```
- 使用 React cache() 实现请求去重
```
cache-segment-config
```
- 通过导出配置路由段缓存

3. Server Components & Data Fetching (HIGH)

3. 服务端组件与数据获取（高）

```
server-parallel-fetching
```
- Fetch Data in Parallel in Server Components
```
server-component-streaming
```
- Stream Server Components for Progressive Loading
```
server-data-colocation
```
- Colocate Data Fetching with Components
```
server-preload-pattern
```
- Use Preload Pattern for Critical Data
```
server-avoid-client-fetching
```
- Avoid Client-Side Data Fetching for Initial Data
```
server-error-handling
```
- Handle Server Component Errors Gracefully

```
server-parallel-fetching
```
- 在服务端组件中并行获取数据
```
server-component-streaming
```
- 流式传输服务端组件以实现渐进式加载
```
server-data-colocation
```
- 将数据获取逻辑与组件就近放置
```
server-preload-pattern
```
- 对关键数据使用预加载模式
```
server-avoid-client-fetching
```
- 初始数据避免使用客户端数据获取
```
server-error-handling
```
- 优雅处理服务端组件错误

4. Routing & Navigation (HIGH)

4. 路由与导航（高）

```
route-parallel-routes
```
- Use Parallel Routes for Independent Content
```
route-intercepting-routes
```
- Use Intercepting Routes for Modal Patterns
```
route-prefetching
```
- Configure Link Prefetching Appropriately
```
route-proxy-ts
```
- Use proxy.ts for Network Boundary Logic
```
route-not-found
```
- Use notFound() for Missing Resources

```
route-parallel-routes
```
- 使用并行路由实现独立内容展示
```
route-intercepting-routes
```
- 使用拦截路由实现模态框模式
```
route-prefetching
```
- 合理配置 Link 预加载
```
route-proxy-ts
```
- 使用 proxy.ts 处理网络边界逻辑
```
route-not-found
```
- 使用 notFound() 处理资源缺失场景

5. Server Actions & Mutations (MEDIUM-HIGH)

5. Server Actions 与数据变更（中高）

```
action-server-action-forms
```
- Use Server Actions for Form Submissions
```
action-pending-states
```
- Show Pending States with useFormStatus
```
action-error-handling
```
- Handle Server Action Errors Gracefully
```
action-optimistic-updates
```
- Use Optimistic Updates for Instant Feedback
```
action-revalidation
```
- Revalidate Cache After Mutations

```
action-server-action-forms
```
- 使用 Server Actions 处理表单提交
```
action-pending-states
```
- 结合 useFormStatus 展示等待状态
```
action-error-handling
```
- 优雅处理 Server Actions 错误
```
action-optimistic-updates
```
- 使用乐观更新实现即时反馈
```
action-revalidation
```
- 数据变更后重新验证缓存

6. Streaming & Loading States (MEDIUM)

6. 流式处理与加载状态（中）

```
stream-suspense-boundaries
```
- Place Suspense Boundaries Strategically
```
stream-loading-tsx
```
- Use loading.tsx for Route-Level Loading States
```
stream-error-tsx
```
- Use error.tsx for Route-Level Error Boundaries
```
stream-skeleton-matching
```
- Match Skeleton Dimensions to Actual Content
```
stream-nested-suspense
```
- Nest Suspense for Progressive Disclosure

```
stream-suspense-boundaries
```
- 合理设置 Suspense 边界
```
stream-loading-tsx
```
- 使用 loading.tsx 实现路由级加载状态
```
stream-error-tsx
```
- 使用 error.tsx 实现路由级错误边界
```
stream-skeleton-matching
```
- 保持骨架屏尺寸与实际内容一致
```
stream-nested-suspense
```
- 嵌套使用 Suspense 实现渐进式内容展示

7. Metadata & SEO (MEDIUM)

7. 元数据与 SEO（中）

```
meta-generate-metadata
```
- Use generateMetadata for Dynamic Metadata
```
meta-sitemap
```
- Generate Sitemaps Dynamically
```
meta-robots
```
- Configure Robots for Crawl Control
```
meta-opengraph-images
```
- Generate Dynamic OpenGraph Images

```
meta-generate-metadata
```
- 使用 generateMetadata 生成动态元数据
```
meta-sitemap
```
- 动态生成站点地图
```
meta-robots
```
- 配置 Robots 协议控制爬虫行为
```
meta-opengraph-images
```
- 动态生成 OpenGraph 图片

8. Client Components (LOW-MEDIUM)

8. 客户端组件（中低）

```
client-use-client-boundary
```
- Minimize 'use client' Boundary Scope
```
client-children-pattern
```
- Pass Server Components as Children to Client Components
```
client-hydration-mismatch
```
- Avoid Hydration Mismatches
```
client-third-party-scripts
```
- Load Third-Party Scripts Efficiently

```
client-use-client-boundary
```
- 最小化 'use client' 边界范围
```
client-children-pattern
```
- 将服务端组件作为子组件传递给客户端组件
```
client-hydration-mismatch
```
- 避免 hydration 不匹配问题
```
client-third-party-scripts
```
- 高效加载第三方脚本

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules
build-dynamic-imports - Example rule file
cache-use-cache-directive - Example rule file

阅读单个参考文件获取详细说明和代码示例：

章节定义 - 类别结构与影响级别说明
规则模板 - 添加新规则的模板
build-dynamic-imports - 规则示例文件
cache-use-cache-directive - 规则示例文件

Related Skills

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

包含所有规则详细内容的完整指南：

AGENTS.md