modern-web-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Modern Web Development

现代Web开发

Brandon Fernandez's comprehensive cursor rules for modern web development with TypeScript, Node.js, Next.js 14, React, Supabase, GraphQL, Tailwind CSS, Radix UI, and Shadcn UI.

Brandon Fernandez针对使用TypeScript、Node.js、Next.js 14、React、Supabase、GraphQL、Tailwind CSS、Radix UI和Shadcn UI进行现代Web开发的全面规范。

Key Development Principles

核心开发原则

Code Style and Architecture

代码风格与架构

Write concise, technical responses with accurate TypeScript examples
Employ functional, declarative programming while avoiding class-based approaches
Prioritize iteration and modularization over code duplication
Use descriptive variable names with auxiliary verbs (
```
isLoading
```
,
```
hasError
```
)
Implement the RORO pattern (Receive an Object, Return an Object)

编写简洁、专业的内容，并附带准确的TypeScript示例
采用函数式、声明式编程，避免基于类的实现方式
优先考虑迭代和模块化，避免代码重复
使用包含助动词的描述性变量名（如
```
isLoading
```
、
```
hasError
```
）
实现RORO模式（接收一个对象，返回一个对象）

JavaScript/TypeScript Standards

JavaScript/TypeScript 规范

Use
```
function
```
keyword for pure functions
Omit semicolons
Leverage TypeScript exclusively, preferring interfaces over types
Structure files as: exported component, subcomponents, helpers, static content, types
Minimize unnecessary curly braces in conditionals

纯函数使用
```
function
```
关键字定义
省略分号
仅使用TypeScript，优先选择interfaces而非types
文件结构遵循：导出组件、子组件、辅助函数、静态内容、类型定义的顺序
尽量减少条件语句中不必要的花括号

Error Handling

错误处理

Address errors and edge cases at function entry points
Apply early returns for error conditions avoiding deep nesting
Position the success path last for improved readability
Use guard clauses for precondition validation
Implement user-friendly error messaging

在函数入口处处理错误和边缘情况
针对错误条件使用提前返回，避免深层嵌套
将成功逻辑放在最后，提升代码可读性
使用守卫子句进行前置条件验证
实现用户友好的错误提示信息

React and Next.js Guidelines

React与Next.js 指南

Use functional components with TypeScript interfaces
Write declarative JSX using
```
function
```
declarations
Style with Shadcn UI, Radix, and Tailwind CSS
Implement mobile-first responsive design
Minimize
```
use client
```
,
```
useEffect
```
, and
```
setState
```
- favor React Server Components
Employ Zod for form validation
Wrap client components in Suspense with fallbacks
Use dynamic loading for non-critical components
Optimize images (WebP format, size data, lazy loading)

使用带TypeScript interfaces的函数式组件
使用
```
function
```
声明编写声明式JSX
使用Shadcn UI、Radix和Tailwind CSS进行样式开发
实现移动端优先的响应式设计
尽量减少
```
use client
```
、
```
useEffect
```
和
```
setState
```
的使用，优先选择React Server Components
使用Zod进行表单验证
用Suspense包裹客户端组件并设置加载回退
对非关键组件使用动态加载
优化图片（采用WebP格式、指定尺寸数据、启用懒加载）

Data and State Management

数据与状态管理

Leverage React Server Components for data fetching
Implement the preload pattern to prevent waterfalls
Use Supabase for real-time synchronization and state management
Consider Vercel KV for chat history, rate limiting, and sessions

利用React Server Components进行数据获取
实现预加载模式以避免请求瀑布
使用Supabase进行实时同步和状态管理
可考虑使用Vercel KV存储聊天记录、实现速率限制和会话管理

Supabase and GraphQL

Supabase与GraphQL

Use Supabase client for database interactions and subscriptions
Implement Row Level Security (RLS) policies
Leverage Supabase Auth, Storage, and Edge Functions
Use Genql for type-safe GraphQL API interactions
Optimize GraphQL queries to fetch only necessary data

使用Supabase客户端进行数据库交互和订阅
实现行级安全（RLS）策略
利用Supabase Auth、Storage和Edge Functions
使用Genql进行类型安全的GraphQL API交互
优化GraphQL查询，仅获取必要数据

Styling and Testing

样式与测试

Styling

样式

Apply Tailwind CSS utility-first approach
Use Class Variance Authority (CVA) for component variants

采用Tailwind CSS的实用优先方法
使用Class Variance Authority (CVA) 实现组件变体

Testing

测试

Implement unit tests for utilities and hooks
Create integration tests for complex components
Develop end-to-end tests for critical user flows

为工具函数和hooks编写单元测试
为复杂组件创建集成测试
为关键用户流程开发端到端测试

Accessibility and Documentation

可访问性与文档

Accessibility

可访问性

Ensure keyboard navigation throughout interfaces
Implement proper ARIA labels and semantic roles
Maintain WCAG-compliant color contrast ratios

确保界面全程支持键盘导航
实现正确的ARIA标签和语义化角色
保持符合WCAG标准的颜色对比度

Documentation

文档

Provide clear JSDoc comments for IDE intellisense
Document Supabase schemas, RLS policies, and Edge Functions

提供清晰的JSDoc注释以支持IDE智能提示
记录Supabase schema、RLS策略和Edge Functions