Back to Details

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:
  1. Read AGENTS.md overview
  2. Identify issue: Server Action needs authentication
  3. Load server-actions-security.md
  4. Apply authentication pattern with validation
任务： "给这个 Server Action 添加认证"
步骤：
  1. 阅读 AGENTS.md 概览
  2. 识别问题：Server Action 需要认证
  3. 加载 server-actions-security.md
  4. 应用带验证的认证模式

Example 2: Eliminating Waterfalls

示例 2：消除请求瀑布

Task: "This page loads slowly with multiple fetches"
Approach:
  1. Read AGENTS.md overview
  2. Identify issue: Sequential data fetching
  3. Load prevent-waterfall-chains.md and parallelize-independent-operations.md
  4. Start operations immediately and use Promise.allSettled()
任务： "这个页面因为多次请求加载缓慢"
步骤：
  1. 阅读 AGENTS.md 概览
  2. 识别问题：串行数据获取
  3. 加载 prevent-waterfall-chains.md 和 parallelize-independent-operations.md
  4. 立即启动操作并使用 Promise.allSettled()

Example 3: Reducing Serialization

示例 3：减少序列化体积

Task: "The HTML response is huge with user data"
Approach:
  1. Read AGENTS.md overview
  2. Identify issue: Over-serialization at RSC boundary
  3. Load minimize-serialization.md
  4. Pass only necessary fields, transform on client
任务： "HTML 响应包含大量用户数据，体积过大"
步骤：
  1. 阅读 AGENTS.md 概览
  2. 识别问题：RSC 边界处过度序列化
  3. 加载 minimize-serialization.md
  4. 仅传递必要字段，在客户端进行转换

Additional Resources

额外资源

Official Next.js documentation:
Next.js 官方文档：