accelint-nextjs-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js Best Practices

Next.js 最佳实践

Comprehensive performance optimization and best practices for Next.js applications, designed for AI agents and LLMs working with Next.js code.

面向使用 Next.js 代码的 AI Agent 和大语言模型的 Next.js 应用全方位性能优化与最佳实践指南。

When to Activate This Skill

何时启用该技能

Use this skill when the task involves:

当任务涉及以下场景时使用本技能：

Writing Next.js Code

编写 Next.js 代码

Creating Server Components or Client Components
Implementing Server Actions with
```
"use server"
```
Writing API route handlers
Setting up data fetching in RSC (React Server Components)
Implementing Suspense boundaries
Using Next.js-specific APIs (
```
headers()
```
,
```
cookies()
```
,
```
after()
```
)

创建 Server Components 或 Client Components
实现带有
```
"use server"
```
的 Server Actions
编写 API 路由处理器
在 RSC（React Server Components）中配置数据获取
实现 Suspense 边界
使用 Next.js 专属 API（
```
headers()
```
、
```
cookies()
```
、
```
after()
```
）

Refactoring Next.js Code

重构 Next.js 代码

Optimizing server-side data fetching
Reducing RSC serialization overhead
Converting sequential to parallel operations
Restructuring component composition for better performance
Migrating between Server and Client Components

优化服务端数据获取
降低 RSC 序列化开销
将串行操作转换为并行操作
重构组件结构以提升性能
在 Server 和 Client Components 之间迁移

Performance Optimization

性能优化

Eliminating server-side waterfalls
Reducing response times in API routes and Server Actions
Minimizing data transfer at RSC boundaries
Implementing request deduplication with
```
React.cache()
```
Using
```
after()
```
for non-blocking operations

消除服务端请求瀑布
降低 API 路由和 Server Actions 的响应时间
减少 RSC 边界处的数据传输量
使用
```
React.cache()
```
实现请求去重
使用
```
after()
```
处理非阻塞操作

Next.js-Specific Issues

Next.js 专属问题

Authentication/authorization in Server Actions
RSC serialization duplication problems
Import optimization (barrel file issues)
Server vs Client Component decision-making
Parallel data fetching patterns

Server Actions 中的认证/授权
RSC 序列化重复问题
导入优化（桶文件问题）
Server 与 Client Component 的选型决策
并行数据获取模式

Code Review

代码审核

Reviewing Next.js code for performance anti-patterns
Identifying security issues in Server Actions
Checking proper Server/Client Component boundaries
Ensuring proper authentication patterns
Validating Suspense boundary placement

审核 Next.js 代码中的性能反模式
识别 Server Actions 中的安全问题
检查 Server/Client Component 边界的正确性
确保认证模式合规
验证 Suspense 边界的放置合理性

When NOT to Use This Skill

何时禁用该技能

Do not activate for:

React-specific optimizations (use
```
accelint-react-best-practices
```
skill)
Build configuration (webpack, turbopack) unless Next.js-specific
General TypeScript/JavaScript questions (use
```
accelint-ts-best-practices
```
skill)
Deployment/hosting configuration
Testing setup (use
```
accelint-ts-testing
```
skill)

请勿在以下场景启用：

仅针对 React 的优化（使用
```
accelint-react-best-practices
```
技能）
构建配置（webpack、turbopack），除非是 Next.js 专属配置
通用 TypeScript/JavaScript 问题（使用
```
accelint-ts-best-practices
```
技能）
部署/托管配置
测试环境搭建（使用
```
accelint-ts-testing
```
技能）

Example Trigger Phrases

触发示例语句

This skill should activate when users say things like:

Performance Issues:

"This Next.js API route is slow"
"My Server Component is blocking the entire page"
"Optimize this Server Action"
"The page takes forever to load data"
"There's a waterfall in my data fetching"

Security Issues:

"Add authentication to this Server Action"
"This Server Action needs authorization"
"Secure this API route"
"Validate input in this Server Action"

Debugging Issues:

"Why is my RSC props so large?"
"This data is being duplicated in the HTML"
"My imports are slow in development"
"Should this be a Server or Client Component?"

Code Review:

"Review this Next.js code for performance issues"
"Is this Server Action secure?"
"Can you optimize this data fetching?"
"Check if this component should be server or client"

Refactoring:

"Parallelize these data fetches"
"Reduce the serialization size"
"Convert this to use Suspense"
"Optimize this barrel import"

当用户说出以下类似内容时，应激活本技能：

性能问题类：

"这个 Next.js API 路由响应很慢"
"我的 Server Component 阻塞了整个页面加载"
"优化这个 Server Action"
"页面加载数据的时间太长了"
"我的数据获取存在请求瀑布问题"

安全问题类：

"给这个 Server Action 添加认证"
"这个 Server Action 需要授权"
"保护这个 API 路由"
"验证这个 Server Action 的输入"

调试问题类：

"为什么我的 RSC props 体积这么大？"
"这些数据在 HTML 中重复了"
"开发环境下我的导入速度很慢"
"这个组件应该是 Server 还是 Client 类型？"

代码审核类：

"审核这段 Next.js 代码的性能问题"
"这个 Server Action 安全吗？"
"你能优化这个数据获取逻辑吗？"
"检查这个组件应该是 Server 还是 Client 类型"

重构类：

"并行化这些数据请求"
"减少序列化体积"
"将这个逻辑改为使用 Suspense"
"优化这个桶文件导入"

How to Use

使用方法

This skill uses a progressive disclosure structure to minimize context usage:

本技能采用渐进式披露结构，以最小化上下文占用：

1. Start with the Overview (AGENTS.md)

1. 从概览开始（AGENTS.md）

Read AGENTS.md for a concise overview of all rules with one-line summaries.

阅读 AGENTS.md 获取所有规则的简洁概览及单行摘要。

2. Load Specific Rules as Needed

2. 根据需要加载特定规则

When you identify a relevant optimization, load the corresponding reference file for detailed implementation guidance:

General Patterns:

prevent-waterfall-chains.md (1.1)
parallelize-independent-operations.md (1.2)
strategic-suspense-boundaries.md (1.3)

Server-Side Performance:

server-actions-security.md (2.1)
avoid-duplicate-serialization.md (2.2)
minimize-serialization.md (2.3)
parallel-data-fetching.md (2.4)
react-cache-deduplication.md (2.5)
use-after-non-blocking.md (2.6)

Misc:

avoid-barrel-imports.md (3.1)
server-vs-client-component.md (3.2)

Quick References:

quick-checklist.md
compound-patterns.md

Automation Scripts:

scripts/ - Helper scripts to detect anti-patterns

当识别到相关优化点时，加载对应的参考文件获取详细实现指南：

通用模式：

prevent-waterfall-chains.md (1.1)
parallelize-independent-operations.md (1.2)
strategic-suspense-boundaries.md (1.3)

服务端性能：

server-actions-security.md (2.1)
avoid-duplicate-serialization.md (2.2)
minimize-serialization.md (2.3)
parallel-data-fetching.md (2.4)
react-cache-deduplication.md (2.5)
use-after-non-blocking.md (2.6)

其他：

avoid-barrel-imports.md (3.1)
server-vs-client-component.md (3.2)

快速参考：

quick-checklist.md
compound-patterns.md

自动化脚本：

scripts/ - 用于检测反模式的辅助脚本

3. Apply the Pattern

3. 应用模式

Each reference file contains:

❌ Incorrect examples showing the anti-pattern
✅ Correct examples showing the optimal implementation
Explanations of why the pattern matters
Performance impact metrics
Related patterns and references

每个参考文件包含：

❌ 展示反模式的错误示例
✅ 展示最优实现的正确示例
该模式重要性的解释
性能影响指标
相关模式及参考资料

4. Use the Report Template

4. 使用报告模板

When this skill is invoked for Next.js code review, use the standardized report format:

Template:

assets/output-report-template.md

The report format provides:

Executive Summary with impact assessment
Severity levels (Critical, High, Medium, Low) for prioritization
Impact analysis (performance, security, data transfer, maintainability)
Categorization (Server Actions, RSC Serialization, Data Fetching, Component Architecture)
Pattern references linking to detailed guidance in references/
Summary table for tracking all issues

When to use the report template:

Skill invoked directly via
```
/accelint-nextjs-best-practices <path>
```
User asks to "review Next.js code" or "audit Next.js app" across file(s), invoking skill implicitly

When NOT to use the report template:

User asks to "fix this Server Action" (direct implementation)
User asks "what's wrong with this code?" (answer the question)
User requests specific fixes (apply fixes directly without formal report)

当本技能被调用进行 Next.js 代码审核时，请使用标准化报告格式：

模板：

assets/output-report-template.md

该报告格式包含：

带有影响评估的执行摘要
用于优先级排序的严重级别（Critical、High、Medium、Low）
影响分析（性能、安全、数据传输、可维护性）
分类（Server Actions、RSC 序列化、数据获取、组件架构）
链接至 references/ 中详细指南的模式参考
用于跟踪所有问题的汇总表格

何时使用报告模板：

通过
```
/accelint-nextjs-best-practices <path>
```
直接调用技能
用户要求“审核 Next.js 代码”或“审计 Next.js 应用”（跨文件），隐式调用技能

何时不使用报告模板：

用户要求“修复这个 Server Action”（直接实现修复）
用户询问“这段代码有什么问题？”（直接回答问题）
用户请求特定修复（直接应用修复，无需正式报告）

Examples

示例

Example 1: Optimizing Server Action Security

示例 1：优化 Server Action 安全性

Task: "Add authentication to this Server Action"

Approach:

Read AGENTS.md overview
Identify issue: Server Action needs authentication
Load server-actions-security.md
Apply authentication pattern with validation

任务： "给这个 Server Action 添加认证"

步骤：

阅读 AGENTS.md 概览
识别问题：Server Action 需要认证
加载 server-actions-security.md
应用带验证的认证模式

Example 2: Eliminating Waterfalls

示例 2：消除请求瀑布

Task: "This page loads slowly with multiple fetches"

Approach:

Read AGENTS.md overview
Identify issue: Sequential data fetching
Load prevent-waterfall-chains.md and parallelize-independent-operations.md
Start operations immediately and use Promise.allSettled()

任务： "这个页面因为多次请求加载缓慢"

步骤：

阅读 AGENTS.md 概览
识别问题：串行数据获取
加载 prevent-waterfall-chains.md 和 parallelize-independent-operations.md
立即启动操作并使用 Promise.allSettled()

Example 3: Reducing Serialization

示例 3：减少序列化体积

Task: "The HTML response is huge with user data"

Approach:

Read AGENTS.md overview
Identify issue: Over-serialization at RSC boundary
Load minimize-serialization.md
Pass only necessary fields, transform on client

任务： "HTML 响应包含大量用户数据，体积过大"

步骤：

阅读 AGENTS.md 概览
识别问题：RSC 边界处过度序列化
加载 minimize-serialization.md
仅传递必要字段，在客户端进行转换

Additional Resources

额外资源

Official Next.js documentation:

Next.js 官方文档：