Back to Details

accelint-react-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

React Best Practices

React最佳实践

Comprehensive performance optimization and best practices for React applications, designed for AI agents and LLMs working with React code.
针对React应用的全面性能优化与最佳实践指南，专为处理React代码的AI Agent和大语言模型设计。

When to Activate This Skill

何时启用此技能

Use this skill when the task involves:
当任务涉及以下场景时，使用此技能：

Writing React Code

编写React代码

  • Creating new React components or hooks
  • Writing JSX elements or fragments
  • Implementing state management with 
    useState
    , 
    useReducer
    , etc.
  • Setting up effects with 
    useEffect
    , 
    useLayoutEffect
  • Creating memoized values or components with 
    useMemo
    , 
    useCallback
    , 
    memo()
  • 创建新的React组件或Hooks
  • 编写JSX元素或片段
  • 使用
    useState
    、
    useReducer
    等实现状态管理
  • 通过
    useEffect
    、
    useLayoutEffect
    设置Effect
  • 使用
    useMemo
    、
    useCallback
    、
    memo()
    创建记忆化值或组件

Refactoring React Code

重构React代码

  • Optimizing component re-renders
  • Reducing unnecessary state updates
  • Simplifying complex effect dependencies
  • Extracting components for better composition
  • Converting class components to functional components
  • 优化组件重渲染
  • 减少不必要的状态更新
  • 简化复杂的Effect依赖项
  • 提取组件以提升组合性
  • 将类组件转换为函数组件

Performance Optimization

性能优化

  • Investigating slow renders or UI jank
  • Reducing bundle size (hoisting static JSX, optimizing SVG)
  • Implementing lazy loading or code splitting
  • Optimizing list rendering (virtualization, content-visibility)
  • Fixing memory leaks in effects or subscriptions
  • 调查渲染缓慢或UI卡顿问题
  • 减小包体积（提升静态JSX、优化SVG）
  • 实现懒加载或代码分割
  • 优化列表渲染（虚拟化、content-visibility）
  • 修复Effect或订阅中的内存泄漏

React-Specific Issues

React特定问题

  • Resolving hydration mismatches in SSR/SSG applications
  • Fixing stale closure bugs in callbacks
  • Debugging infinite re-render loops
  • Preventing unnecessary effect re-runs
  • Managing derived state correctly
  • 解决SSR/SSG应用中的hydration不匹配问题
  • 修复回调中的闭包过期问题
  • 调试无限重渲染循环
  • 避免不必要的Effect重运行
  • 正确管理派生状态

Code Review

代码审查

  • Reviewing React code for performance anti-patterns
  • Identifying improper use of hooks
  • Checking for React 19 deprecated patterns (
    forwardRef
    , default imports)
  • Ensuring proper memoization strategies
  • 审查React代码中的性能反模式
  • 识别Hooks的不当使用
  • 检查React 19已弃用模式（
    forwardRef
    、默认导入）
  • 确保采用正确的记忆化策略

When NOT to Use This Skill

何时不使用此技能

Do not activate for:
  • General JavaScript/TypeScript questions unrelated to React
  • Build configuration (webpack, vite, etc.) unless React-specific
  • CSS styling unless related to React performance (animations, content-visibility)
  • Backend API development
  • Testing setup (use a testing-specific skill if available)
请勿在以下场景启用：
  • 与React无关的通用JavaScript/TypeScript问题
  • 构建配置（webpack、vite等），除非是React特定的配置
  • CSS样式，除非与React性能相关（动画、content-visibility）
  • 后端API开发
  • 测试设置（如有专门的测试技能，请使用该技能）

Example Trigger Phrases

示例触发语

This skill should activate when users say things like:
Performance Issues:
  • "This component is re-rendering too much"
  • "My React app is slow when scrolling"
  • "Optimize this React component for performance"
  • "The input feels laggy when typing"
  • "This page takes forever to load initially"
Debugging Issues:
  • "Why is my useEffect running infinitely?"
  • "I'm getting hydration errors in Next.js"
  • "This callback always has stale/old values"
  • "My effect keeps re-subscribing to events"
Code Review:
  • "Review this React code for performance issues"
  • "Is this React component following best practices?"
  • "Can you optimize this React hook?"
  • "Check if this component has any performance problems"
React 19 Migration:
  • "Update this code to React 19"
  • "Replace forwardRef with the new pattern"
  • "Fix these React 19 deprecation warnings"
  • "Migrate to React 19 best practices"
Refactoring:
  • "Refactor this component to be more performant"
  • "Clean up these useEffect dependencies"
  • "Improve the performance of this list rendering"
当用户说出以下内容时，应启用此技能：
性能问题：
  • "这个组件重渲染太频繁了"
  • "我的React应用滚动时很卡"
  • "优化这个React组件的性能"
  • "输入时感觉延迟"
  • "这个页面初始加载时间太长"
调试问题：
  • "为什么我的useEffect无限运行？"
  • "我在Next.js中遇到了hydration错误"
  • "这个回调总是使用旧的状态值"
  • "我的Effect一直在重新订阅事件"
代码审查：
  • "审查这段React代码的性能问题"
  • "这个React组件是否遵循最佳实践？"
  • "你能优化这个React Hook吗？"
  • "检查这个组件是否有性能问题"
React 19迁移：
  • "将这段代码更新到React 19"
  • "用新模式替换forwardRef"
  • "修复这些React 19弃用警告"
  • "迁移到React 19最佳实践"
重构：
  • "重构这个组件以提升性能"
  • "清理这些useEffect依赖项"
  • "提升这个列表渲染的性能"

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:
Re-render Optimizations:
  • defer-state-reads.md
  • extract-memoized-components.md
  • narrow-effect-dependencies.md
  • subscribe-derived-state.md
  • functional-setstate-updates.md
  • lazy-state-initialization.md
  • transitions-non-urgent-updates.md
  • calculate-derived-state.md
  • avoid-usememo-simple-expressions.md
  • extract-default-parameter-value.md
  • interaction-logic-in-event-handlers.md
  • useref-for-transient-values.md
Rendering Performance:
  • animate-svg-wrapper.md
  • css-content-visibility.md
  • hoist-static-jsx.md
  • optimize-svg-precision.md
  • prevent-hydration-mismatch.md
  • activity-component-show-hide.md
  • hoist-regexp-creation.md
  • use-usetransition-over-manual-loading.md
Advanced Patterns:
  • store-event-handlers-refs.md
  • uselatest-stable-callbacks.md
  • cache-repeated-function-calls.md
  • initialize-app-once.md
Misc:
  • named-imports.md
  • no-forwardref.md
Quick References:
  • quick-checklists.md
  • compound-patterns.md
  • react-compiler-guide.md
Automation Scripts:
  • scripts/ - Helper scripts to detect anti-patterns
当确定相关优化方向时，加载对应的参考文件获取详细的实现指导：
重渲染优化：
  • defer-state-reads.md
  • extract-memoized-components.md
  • narrow-effect-dependencies.md
  • subscribe-derived-state.md
  • functional-setstate-updates.md
  • lazy-state-initialization.md
  • transitions-non-urgent-updates.md
  • calculate-derived-state.md
  • avoid-usememo-simple-expressions.md
  • extract-default-parameter-value.md
  • interaction-logic-in-event-handlers.md
  • useref-for-transient-values.md
渲染性能：
  • animate-svg-wrapper.md
  • css-content-visibility.md
  • hoist-static-jsx.md
  • optimize-svg-precision.md
  • prevent-hydration-mismatch.md
  • activity-component-show-hide.md
  • hoist-regexp-creation.md
  • use-usetransition-over-manual-loading.md
高级模式：
  • store-event-handlers-refs.md
  • uselatest-stable-callbacks.md
  • cache-repeated-function-calls.md
  • initialize-app-once.md
其他：
  • named-imports.md
  • no-forwardref.md
快速参考：
  • quick-checklists.md
  • compound-patterns.md
  • react-compiler-guide.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
每个参考文件包含：
  • ❌ 展示反模式的错误示例
  • ✅ 展示最佳实现的正确示例
  • 该模式重要性的解释

4. Use the Report Template

4. 使用报告模板

When this skill is invoked, 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 (potential bugs, type safety, maintainability, runtime failures)
  • Categorization (Type Safety, Safety, State Management, Return Values, Code Quality)
  • Pattern references linking to detailed guidance in references/
  • Phase 2 summary table for tracking all issues
When to use the audit template:
  • Skill invoked directly via 
    /accelint-ts-best-practices <path>
  • User asks to "review code quality" or "audit code" across file(s), invoking skill implicitly
When NOT to use the report template:
  • User asks to "fix this type error" (direct implementation)
  • User asks "what's wrong with this code?" (answer the question)
  • User requests specific fixes (apply fixes directly without formal report)
当调用此技能时，使用标准化报告格式：
模板： 
assets/output-report-template.md
报告格式包含：
  • 带有影响评估的执行摘要
  • 用于优先级排序的严重程度级别（Critical、High、Medium、Low）
  • 影响分析（潜在bug、类型安全、可维护性、运行时故障）
  • 分类（类型安全、安全性、状态管理、返回值、代码质量）
  • 指向references/中详细指导的模式引用
  • 用于跟踪所有问题的第二阶段汇总表
何时使用审计模板：
  • 通过
    /accelint-ts-best-practices <path>
    直接调用技能
  • 用户要求“审查代码质量”或“审计代码”（跨文件），间接调用技能
何时不使用报告模板：
  • 用户要求“修复这个类型错误”（直接实现）
  • 用户询问“这段代码有什么问题？”（直接回答问题）
  • 用户要求特定修复（直接应用修复，无需正式报告）

Examples

示例

Example 1: Optimizing Re-renders

示例1：优化重渲染

Task: "This component re-renders too frequently when the user scrolls"
Approach:
  1. Read AGENTS.md overview
  2. Identify likely cause: subscribing to continuous values (scroll position)
  3. Load subscribe-derived-state.md or transitions-non-urgent-updates.md
  4. Apply the pattern from the reference file
任务： “这个组件在用户滚动时重渲染过于频繁”
方法：
  1. 阅读AGENTS.md概述
  2. 确定可能原因：订阅了连续变化的值（滚动位置）
  3. 加载subscribe-derived-state.md或transitions-non-urgent-updates.md
  4. 应用参考文件中的模式

Example 2: Fixing Stale Closures

示例2：修复闭包过期问题

Task: "This callback always uses the old state value"
Approach:
  1. Read AGENTS.md overview
  2. Identify issue: stale closure in useCallback
  3. Load functional-setstate-updates.md
  4. Replace direct state reference with functional update
任务： “这个回调总是使用旧的状态值”
方法：
  1. 阅读AGENTS.md概述
  2. 确定问题：useCallback中的闭包过期
  3. 加载functional-setstate-updates.md
  4. 用函数式更新替换直接状态引用

Example 3: SSR Hydration Mismatch

示例3：SSR Hydration不匹配

Task: "Getting hydration errors with localStorage theme"
Approach:
  1. Read AGENTS.md overview
  2. Identify issue: client-only state causing mismatch
  3. Load prevent-hydration-mismatch.md
  4. Implement synchronous script pattern
任务： “使用localStorage主题时出现hydration错误”
方法：
  1. 阅读AGENTS.md概述
  2. 确定问题：仅客户端状态导致不匹配
  3. 加载prevent-hydration-mismatch.md
  4. 实现同步脚本模式

Important Notes

重要说明

React Compiler Awareness

React编译器注意事项

Many manual optimization patterns (memo, useMemo, useCallback, hoisting static JSX) are automatically handled by React Compiler.
Before optimizing, check if the project uses React Compiler:
  • If enabled: Skip manual memoization, but still apply state/effect/CSS optimizations
  • If not enabled: Apply all relevant optimizations from this guide
See react-compiler-guide.md for a complete breakdown of what the compiler handles vs what still needs manual optimization.
许多手动优化模式（memo、useMemo、useCallback、提升静态JSX）已由React Compiler自动处理。
优化前，请检查项目是否使用React Compiler：
  • 若已启用：跳过手动记忆化，但仍需应用状态/Effect/CSS优化
  • 若未启用：应用本指南中的所有相关优化
请查看react-compiler-guide.md，了解编译器处理的内容与仍需手动优化的内容的完整说明。

React 19+ Features

React 19+特性

This skill covers React 19 features including:
  • useEffectEvent
    (19.2+) for stable event handlers
  • <Activity>
    component for preserving hidden component state
  • ref
    as a prop (replaces deprecated 
    forwardRef
    )
  • Named imports only (no default import of React)
此技能涵盖React 19特性，包括：
  • useEffectEvent
    （19.2+）：用于稳定的事件处理程序
  • <Activity>
    组件：用于保留隐藏组件的状态
  • ref
    作为属性：替代已弃用的
    forwardRef
  • 仅命名导入：不允许默认导入React

Performance Philosophy

性能理念

  • Start with correct code, then optimize
  • Measure before optimizing
  • Optimize slowest operations first (network > rendering > computation)
  • Avoid premature optimization of trivial operations
  • 先保证代码正确，再进行优化
  • 先测量，再优化
  • 优先优化最慢的操作（网络 > 渲染 > 计算）
  • 避免对无关紧要的操作进行过早优化

Code Quality Principles

代码质量原则

  • Prefer simple, readable code over clever optimizations
  • Only add complexity when measurements justify it
  • Document non-obvious performance optimizations
  • 优先选择简单、可读的代码，而非巧妙的优化
  • 仅当测量结果证明必要时才增加复杂度
  • 对非显而易见的性能优化进行文档说明

Additional Resources

额外资源

Catch up on React 19 features:
了解React 19特性：