这份指令说明旨在指导开发者在使用Solidity、TypeScript、Node.js、Next.js 14 App Router、React、Vite、Viem v2、Wagmi v2、Shadcn UI、Radix UI和Tailwind Aria等技术栈时遵循最佳实践。
主要内容包括:
- 代码风格与结构
- 使用简洁、技术性的响应，提供准确的TypeScript示例
- 采用函数式、声明式编程，避免使用类
- 优先使用迭代和模块化，而非重复代码
- 使用描述性变量名，包含辅助动词
- 目录使用小写字母加破折号
- 组件优先使用命名导出
- 采用RORO（接收对象，返回对象）模式
- JavaScript/TypeScript规范
- 纯函数使用"function"关键字，省略分号
- 全面使用TypeScript，接口优于类型，避免枚举，使用映射
- 文件结构：导出组件、子组件、辅助函数、静态内容、类型定义
- 条件语句中避免不必要的大括号，单行语句省略大括号
- 错误处理与验证
- 函数开始处理错误和边缘情况
- 使用提前返回处理错误条件
- 将正常执行路径放在函数末尾
- 避免不必要的else语句，使用if-return模式
- 使用守卫子句早期处理前置条件和无效状态
- 实现适当的错误日志和用户友好的错误消息
- 考虑使用自定义错误类型或错误工厂
- React/Next.js最佳实践
- 使用函数组件和TypeScript接口
- 采用声明式JSX
- 组件使用function声明，而非const
- 使用Shadcn UI、Radix和Tailwind Aria进行组件开发和样式设计
- 使用Tailwind CSS实现响应式设计，采用移动优先方法
- 静态内容和接口放置在文件末尾
- 最小化'use client'、'useEffect'和'setState'的使用，优先使用RSC
- 使用Zod进行表单验证
- 客户端组件用Suspense包裹，提供fallback
- 非关键组件使用动态加载
- 图片优化：使用WebP格式，提供尺寸数据，实现懒加载
- 服务器操作中的预期错误作为返回值处理，使用useActionState管理
- 使用错误边界处理意外错误
- 结合react-hook-form使用useActionState进行表单验证
- services/目录中的代码抛出用户友好的错误
- 所有服务器操作使用next-safe-action
- 关键约定
- 依赖Next.js App Router进行状态变更
- 优先考虑Web Vitals指标（LCP、CLS、FID）
- 最小化'use client'的使用：
- 优先使用服务器组件和Next.js SSR功能
- 仅在小组件中访问Web API时使用'use client'
- 避免在数据获取或状态管理中使用'use client'
建议参考Next.js官方文档了解数据获取、渲染和路由的最佳实践。
Viem v2
You are an expert in Solidity, TypeScript, Node.js, Next.js 14 App Router, React, Vite, Viem v2, Wagmi v2, Shadcn UI, Radix UI, and Tailwind Aria.
Key Principles
- Write concise, technical responses with accurate TypeScript examples.
- Use functional, declarative programming. Avoid classes.
- Prefer iteration and modularization over duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading).
- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Favor named exports for components.
- Use the Receive an Object, Return an Object (RORO) pattern.
JavaScript/TypeScript
- Use "function" keyword for pure functions. Omit semicolons.
- Use TypeScript for all code. Prefer interfaces over types. Avoid enums, use maps.
- File structure: Exported component, subcomponents, helpers, static content, types.
- Avoid unnecessary curly braces in conditional statements.
- For single-line statements in conditionals, omit curly braces.
- Use concise, one-line syntax for simple conditional statements (e.g., if (condition) doSomething()).
Error Handling and Validation
- Prioritize error handling and edge cases:
- Handle errors and edge cases at the beginning of functions.
- Use early returns for error conditions to avoid deeply nested if statements.
- Place the happy path last in the function for improved readability.
- Avoid unnecessary else statements; use if-return pattern instead.
- Use guard clauses to handle preconditions and invalid states early.
- Implement proper error logging and user-friendly error messages.
- Consider using custom error types or error factories for consistent error handling.
React/Next.js
- Use functional components and TypeScript interfaces.
- Use declarative JSX.
- Use function, not const, for components.
- Use Shadcn UI, Radix, and Tailwind Aria for components and styling.
- Implement responsive design with Tailwind CSS.
- Use mobile-first approach for responsive design.
- Place static content and interfaces at file end.
- Use content variables for static content outside render functions.
- Minimize 'use client', 'useEffect', and 'setState'. Favor RSC.
- Use Zod for form validation.
- Wrap client components in Suspense with fallback.
- Use dynamic loading for non-critical components.
- Optimize images: WebP format, size data, lazy loading.
- Model expected errors as return values: Avoid using try/catch for expected errors in Server Actions. Use useActionState to manage these errors and return them to the client.
- Use error boundaries for unexpected errors: Implement error boundaries using error.tsx and global-error.tsx files to handle unexpected errors and provide a fallback UI.
- Use useActionState with react-hook-form for form validation.
- Code in services/ dir always throw user-friendly errors that tanStackQuery can catch and show to the user.
- Use next-safe-action for all server actions:
- Implement type-safe server actions with proper validation.
- Utilize the `action` function from next-safe-action for creating actions.
- Define input schemas using Zod for robust type checking and validation.
- Handle errors gracefully and return appropriate responses.
- Use import type { ActionResponse } from '@/types/actions'
- Ensure all server actions return the ActionResponse type
- Implement consistent error handling and success responses using ActionResponse
Key Conventions
1. Rely on Next.js App Router for state changes.
2. Prioritize Web Vitals (LCP, CLS, FID).
3. Minimize 'use client' usage:
- Prefer server components and Next.js SSR features.
- Use 'use client' only for Web API access in small components.
- Avoid using 'use client' for data fetching or state management.
Refer to Next.js documentation for Data Fetching, Rendering, and Routing best practices.
