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	构建与打包优化	关键	`build-`
2	缓存策略	关键	`cache-`
3	Server Components与数据获取	高	`server-`
4	路由与导航	高	`route-`
5	Server Actions与数据变更	中高	`action-`
6	流式传输与加载状态	中	`stream-`
7	元数据与SEO	中	`meta-`
8	Client Components	中低	`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
```
- Configure Turbopack at the top level
```
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依赖配置Server External Packages

2. Caching Strategy (CRITICAL)

2. 缓存策略（关键）

```
cache-use-cache-directive
```
- Use 'use cache' with Cache Components
```
cache-revalidate-tag
```
- Use revalidateTag with cacheLife Profiles
```
cache-fetch-options
```
- Configure Fetch Cache Options Explicitly
```
cache-revalidate-path
```
- Use revalidatePath for Route-Level Cache Invalidation
```
cache-react-cache
```
- Use React cache() for Request Deduplication
```
cache-segment-config
```
- Match route configuration to the active cache model

```
cache-use-cache-directive
```
- 结合Cache Components使用'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 Components与数据获取（高）

```
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 Components中并行获取数据
```
server-component-streaming
```
- 流式传输Server Components以实现渐进式加载
```
server-data-colocation
```
- 将数据获取逻辑与组件放在同一位置
```
server-preload-pattern
```
- 对关键数据使用预加载模式
```
server-avoid-client-fetching
```
- 初始数据避免使用客户端数据获取
```
server-error-handling
```
- 优雅处理Server Components错误

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 Components（中低）

```
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
```
- 将Server Components作为子组件传递给Client Components
```
client-hydration-mismatch
```
- 避免 hydration 不匹配问题
```
client-third-party-scripts
```
- 高效加载第三方脚本

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

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