nextjs-react-redux-typescript-cursor-rules

Next.js React Redux TypeScript Cursor 规则

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

开发理念

• 遵循 SOLID 原则，编写易于维护、可扩展的代码
• 优先采用函数式和声明式方法，而不是命令式风格
• 优先保证类型安全并进行静态分析
• 采用组件驱动架构

代码风格规范

• 缩进：使用制表符
• 字符串：使用单引号（除非需要转义）
• 分号：除非为消除歧义所必需，否则省略
• 运算符：中缀运算符两侧留空格
• 函数：声明函数时，在括号前留空格
• 相等判断：始终使用 ===，而不是 ==
• 行长：最多 80 个字符
• 条件语句：多行 if 语句使用花括号
• 集合：多行数组/对象末尾添加逗号

命名规范

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

前缀

• 事件处理程序：handle（例如，handleClick）
• 布尔值：使用动词（例如，isLoading、hasError、canSubmit）
• 自定义钩子：use（例如，useAuth、useForm）

React 最佳实践

组件

• 使用带有 TypeScript 接口的函数组件
• 使用 function 关键字定义组件
• 将可复用逻辑提取到自定义钩子中
• 正确应用组合模式
• 有针对性地使用 React.memo()
• 在 useEffect 钩子中实现清理逻辑

性能

• 使用 useCallback 缓存函数
• 使用 useMemo 处理开销较大的计算
• 避免在 JSX 中内联定义函数
• 通过动态导入实现代码拆分
• 在列表中使用恰当的 key 属性（绝不使用索引）

Next.js 最佳实践

核心

• 使用 App Router 进行路由
• 实现元数据管理
• 采用恰当的缓存策略
• 实现错误边界

组件

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

服务端组件

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

TypeScript 实现

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

UI 和样式

库

• Shadcn UI：一致且易于访问的组件
• Radix UI：可自定义的原语
• 组合模式：模块化

样式

• 采用 Tailwind CSS 优先使用工具类的方法
• 采用移动端优先的响应式设计
• 通过 CSS 变量或 Tailwind 的暗色模式实现暗色模式
• 确保颜色对比度符合无障碍要求
• 使用一致的间距值
• 使用 CSS 变量定义主题颜色

状态管理

本地状态

• 使用 useState 管理组件级状态
• 使用 useReducer 管理复杂状态
• 使用 useContext 管理共享状态

全局状态（Redux Toolkit）

• 使用 createSlice 组合状态、reducers 和 actions
• 规范化状态结构
• 使用选择器封装访问逻辑
• 按功能拆分职责（避免使用单体 slice）

错误处理和验证

表单

• 使用 Zod 进行模式验证
• 集成 React Hook Form
• 提供清晰的错误信息

错误边界

• 妥善捕获和处理 React 树中的错误
• 将错误记录到外部服务（例如，Sentry）
• 显示便于用户理解的备用 UI

测试

单元测试

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

集成测试

• 聚焦用户工作流
• 正确设置和清理测试环境
• 有选择地进行快照测试
• 使用测试工具（RTL 中的 screen）

无障碍（a11y）

• 使用语义化 HTML
• 准确设置 ARIA 属性
• 支持完整的键盘导航
• 妥善管理焦点
• 确保颜色对比度符合无障碍要求
• 采用合理的标题层级
• 确保交互元素易于访问
• 提供清晰的错误反馈

安全

• 清理输入以防止 XSS
• 使用 DOMPurify 清理 HTML
• 使用恰当的身份验证方法

国际化（i18n）

• 使用 next-i18next 进行翻译
• 检测区域设置
• 格式化数字和日期
• 支持 RTL
• 格式化货币

文档

• 为所有公共函数、类、方法和接口编写 JSDoc
• 使用完整句子，并正确添加标点
• 编写清晰、简洁的描述
• 正确使用 Markdown、代码块、链接、标题和列表
• 适当提供示例