nextjs-react-redux-typescript-cursor-rules

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js React Redux TypeScript Cursor Rules

Next.js React Redux TypeScript 开发规则

Complete development guidelines for building maintainable, scalable applications with Next.js, React, Redux Toolkit, and TypeScript.

用于基于Next.js、React、Redux Toolkit和TypeScript构建可维护、可扩展应用的完整开发指南。

Development Philosophy

开发理念

Produce maintainable, scalable code following SOLID principles
Favor functional and declarative approaches over imperative styles
Prioritize type safety and static analysis
Embrace component-driven architecture

遵循SOLID原则，编写可维护、可扩展的代码
优先使用函数式和声明式编程，而非命令式风格
优先保障类型安全和静态分析
采用组件驱动架构

Code Style Standards

代码风格规范

Indentation: Use tabs
Strings: Use single quotes (unless escaping needed)
Semicolons: Omit unless disambiguation required
Operators: Space around infix operators
Functions: Space before declaration parentheses
Equality: Always use
```
===
```
over
```
==
```
Line length: Maximum 80 characters
Conditionals: Use braces for multi-line if statements
Collections: Trailing commas in multiline arrays/objects

缩进：使用制表符
字符串：使用单引号（除非需要转义）
分号：可省略，除非需要消除歧义
运算符：中缀运算符两侧保留空格
函数：声明的括号前保留空格
相等判断：始终使用
```
===
```
而非
```
==
```
行长度：最大80个字符
条件语句：多行if语句使用大括号包裹
集合：多行数组/对象末尾保留 trailing comma

Naming Conventions

命名规范

Convention	Usage
PascalCase	Components, type definitions, interfaces
kebab-case	Directory and file names (e.g., `user-profile.tsx` )
camelCase	Variables, functions, methods, hooks, properties, props
UPPERCASE	Environment variables, constants, global configurations

规范	适用场景
PascalCase	组件、类型定义、接口
kebab-case	目录和文件名（例如 `user-profile.tsx` ）
camelCase	变量、函数、方法、hooks、属性、props
UPPERCASE	环境变量、常量、全局配置

Prefixes

前缀规则

Event handlers:
```
handle
```
(e.g.,
```
handleClick
```
)
Booleans: verbs (e.g.,
```
isLoading
```
,
```
hasError
```
,
```
canSubmit
```
)
Custom hooks:
```
use
```
(e.g.,
```
useAuth
```
,
```
useForm
```
)

事件处理器：使用
```
handle
```
前缀（例如
```
handleClick
```
）
布尔值：使用动词开头（例如
```
isLoading
```
、
```
hasError
```
、
```
canSubmit
```
）
自定义hooks：使用
```
use
```
前缀（例如
```
useAuth
```
、
```
useForm
```
）

React Best Practices

React最佳实践

Components

组件

Use functional components with TypeScript interfaces
Define components using
```
function
```
keyword
Extract reusable logic into custom hooks
Apply composition patterns properly
Leverage
```
React.memo()
```
strategically
Implement cleanup in
```
useEffect
```
hooks

使用带TypeScript接口的函数式组件
使用
```
function
```
关键字定义组件
将可复用逻辑抽离到自定义hooks中
合理应用组合模式
策略性地使用
```
React.memo()
```
在
```
useEffect
```
hooks中实现清理逻辑

Performance

性能

Use
```
useCallback
```
for memoizing functions
Apply
```
useMemo
```
for expensive computations
Avoid inline function definitions in JSX
Implement code splitting via dynamic imports
Use proper
```
key
```
props in lists (never use index)

使用
```
useCallback
```
缓存函数
使用
```
useMemo
```
处理昂贵计算
避免在JSX中编写内联函数定义
通过动态导入实现代码分割
列表中使用正确的
```
key
```
属性（永远不要使用索引）

Next.js Best Practices

Next.js最佳实践

Core

核心能力

Use App Router for routing
Implement metadata management
Apply proper caching strategies
Implement error boundaries

使用App Router实现路由
实现元数据管理
应用合理的缓存策略
实现错误边界

Components

组件

Use built-in components:
```
Image
```
,
```
Link
```
,
```
Script
```
,
```
Head
```
Implement loading states
Use appropriate data fetching methods

使用内置组件：
```
Image
```
、
```
Link
```
、
```
Script
```
、
```
Head
```
实现加载状态
使用合适的数据获取方法

Server Components

Default to Server Components
Use URL query parameters for server state
Apply
```
use client
```
only when necessary:
- Event listeners
- Browser APIs
- State management
- Client libraries

默认使用Server Components
使用URL查询参数处理服务端状态
仅在必要时使用
```
use client
```
：
- 事件监听器
- 浏览器API
- 状态管理
- 客户端库

TypeScript Implementation

TypeScript实现规范

Enable strict mode
Define clear interfaces for props, state, and Redux structure
Use type guards for undefined/null safety
Apply generics for flexibility
Leverage utility types (
```
Partial
```
,
```
Pick
```
,
```
Omit
```
)
Prefer
```
interface
```
over
```
type
```
for objects
Use mapped types for dynamic type variations

开启严格模式
为props、state和Redux结构定义清晰的接口
使用类型守卫保障undefined/null安全
应用泛型提升灵活性
使用工具类型（
```
Partial
```
、
```
Pick
```
、
```
Omit
```
）
对象类型优先使用
```
interface
```
而非
```
type
```
使用映射类型实现动态类型变体

UI and Styling

UI与样式

Libraries

组件库

Shadcn UI: Consistent, accessible components
Radix UI: Customizable primitives
Composition patterns: Modularity

Shadcn UI：实现一致、可访问的组件
Radix UI：提供可自定义的基础原语
组合模式：实现模块化

Styling

样式规范

Tailwind CSS utility-first approach
Mobile-first responsive design
Dark mode via CSS variables or Tailwind's dark mode
Accessible color contrast ratios
Consistent spacing values
CSS variables for theme colors

采用Tailwind CSS工具优先的方案
移动端优先的响应式设计
通过CSS变量或Tailwind的暗色模式实现深色模式
符合可访问性要求的颜色对比度
统一的间距值
使用CSS变量定义主题色

State Management

状态管理

Local State

本地状态

```
useState
```
for component-level state
```
useReducer
```
for complex state
```
useContext
```
for shared state

```
useState
```
用于处理组件级状态
```
useReducer
```
用于处理复杂状态
```
useContext
```
用于处理共享状态

Global State (Redux Toolkit)

全局状态（Redux Toolkit）

Use
```
createSlice
```
for combined state/reducers/actions
Normalize state structure
Use selectors for access encapsulation
Separate concerns by feature (avoid monolithic slices)

使用
```
createSlice
```
整合state/reducers/actions
规范化状态结构
使用选择器封装访问逻辑
按业务特性分离关注点（避免单体式slice）

Error Handling and Validation

错误处理与校验

Forms

表单

Zod for schema validation
React Hook Form integration
Clear error messaging

使用Zod做Schema校验
集成React Hook Form
提供清晰的错误提示

Error Boundaries

错误边界

Catch and handle React tree errors gracefully
Log errors to external services (e.g., Sentry)
Display user-friendly fallback UIs

优雅捕获和处理React树错误
将错误上报到外部服务（例如Sentry）
展示对用户友好的降级UI

Testing

测试

Unit Testing

单元测试

Jest and React Testing Library
Arrange-Act-Assert pattern
Mock external dependencies and API calls

使用Jest和React Testing Library
遵循Arrange-Act-Assert模式
模拟外部依赖和API调用

Integration Testing

集成测试

Focus on user workflows
Proper test environment setup/teardown
Selective snapshot testing
Use testing utilities (
```
screen
```
in RTL)

聚焦用户工作流
正确完成测试环境的搭建/销毁
选择性使用快照测试
使用测试工具（RTL中的
```
screen
```
）

Accessibility (a11y)

无障碍（a11y）

Semantic HTML
Accurate ARIA attributes
Full keyboard navigation
Proper focus management
Accessible color contrast
Logical heading hierarchy
Accessible interactive elements
Clear error feedback

语义化HTML
准确的ARIA属性
全键盘导航支持
正确的焦点管理
符合要求的颜色对比度
合理的标题层级
可访问的交互元素
清晰的错误反馈

Security

安全

Input sanitization to prevent XSS
DOMPurify for HTML sanitization
Proper authentication methods

输入消毒防止XSS攻击
使用DOMPurify做HTML消毒
采用合理的身份验证方法

Internationalization (i18n)

国际化（i18n）

next-i18next for translations
Locale detection
Number and date formatting
RTL support
Currency formatting

使用next-i18next实现翻译能力
locale自动检测
数字与日期格式化
RTL布局支持
货币格式化

Documentation

文档

JSDoc for all public functions, classes, methods, interfaces
Complete sentences with proper punctuation
Clear, concise descriptions
Proper markdown, code blocks, links, headings, lists
Examples when appropriate

所有公共函数、类、方法、接口都添加JSDoc注释
使用带正确标点的完整句子
描述清晰简洁
使用正确的markdown格式、代码块、链接、标题、列表
合适的场景下补充示例