react-skills

LlamaFarm Designer 的 React 技能

Designer 子系统中 React 18 开发的最佳实践和模式。

技术栈

• React 18.2，启用 StrictMode
• TypeScript 5.2+，确保类型安全
• TanStack Query v5，用于服务端状态管理
• React Router v7，用于客户端路由
• TailwindCSS，搭配 tailwind-merge 和 clsx 进行样式设置
• Radix UI 原语，用于构建无障碍组件
• Vite，用于构建工具链
• Vitest + React Testing Library，用于测试

目录结构

designer/src/
  api/          # API service functions
  components/   # React components (feature-organized)
  contexts/     # React context providers
  hooks/        # Custom hooks
  lib/          # Utility functions (cn, etc.)
  types/        # TypeScript type definitions
  utils/        # Helper functions
  test/         # Test utilities and mocks

核心模式

组件组合

• 优先使用组合而非继承
• 优先使用小型、专注的组件
• 对包装 DOM 元素的组件使用 forwardRef
• 为使用 forwardRef 的组件设置 displayName，以便在 DevTools 中查看

状态管理

• 本地 UI 状态：useState、useReducer
• 服务端状态：TanStack Query（useQuery、useMutation）
• 共享 UI 状态：使用自定义 Hook 的 React Context
• 表单状态：使用带验证的受控组件

Hook

• 遵循 Hook 规则（在顶层调用，顺序保持一致）
• 为可复用逻辑创建自定义 Hook
• 为 TanStack Query 使用查询键工厂
• 使用 useMemo 缓存开销较大的计算
• 使用 useCallback 稳定回调函数

样式

• 使用 lib/utils 中的 cn() 合并 Tailwind 类
• 使用 cva（class-variance-authority）定义组件变体
• 使用 dark: 前缀遵循暗色模式约定

相关指南

• components.md - 组件模式
• hooks.md - Hook 模式和规则
• state.md - 状态管理模式
• performance.md - 性能优化
• security.md - 安全最佳实践

快速参考

// Utility for merging Tailwind classes
import { cn } from '@/lib/utils'
cn('base-class', condition && 'conditional-class', className)

// Query key factory pattern
export const projectKeys = {
  all: ['projects'] as const,
  lists: () => [...projectKeys.all, 'list'] as const,
  list: (ns: string) => [...projectKeys.lists(), ns] as const,
}

// Context with validation hook
const MyContext = createContext<MyContextType | undefined>(undefined)
export function useMyContext() {
  const ctx = useContext(MyContext)
  if (!ctx) throw new Error('useMyContext must be within MyProvider')
  return ctx
}

测试

import { renderWithProviders } from '@/test/utils'
import { screen } from '@testing-library/react'

test('renders component', () => {
  renderWithProviders(<MyComponent />)
  expect(screen.getByText('Hello')).toBeInTheDocument()
})