react-skills

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Skills for LlamaFarm Designer

面向LlamaFarm Designer的React技能指南

Best practices and patterns for React 18 development in the Designer subsystem.

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

Tech Stack

技术栈

React 18.2 with StrictMode
TypeScript 5.2+ for type safety
TanStack Query v5 for server state management
React Router v7 for client-side routing
TailwindCSS with
```
tailwind-merge
```
and
```
clsx
```
for styling
Radix UI primitives for accessible components
Vite for build tooling
Vitest + React Testing Library for testing

React 18.2（搭配StrictMode）
TypeScript 5.2+（保障类型安全）
TanStack Query v5（服务端状态管理）
React Router v7（客户端路由）
TailwindCSS（结合
```
tailwind-merge
```
和
```
clsx
```
实现样式）
Radix UI（可访问性组件基础库）
Vite（构建工具）
Vitest + React Testing Library（测试框架）

Directory Structure

目录结构

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

designer/src/
  api/          # API服务函数
  components/   # React组件（按功能模块组织）
  contexts/     # React Context提供者
  hooks/        # 自定义Hooks
  lib/          # 工具函数（如cn等）
  types/        # TypeScript类型定义
  utils/        # 辅助函数
  test/         # 测试工具与模拟数据

Core Patterns

核心模式

Component Composition

组件组合

Use composition over inheritance
Prefer small, focused components
Use
```
forwardRef
```
for components that wrap DOM elements
Apply
```
displayName
```
to forwardRef components for DevTools

优先使用组合而非继承
推荐小巧、职责单一的组件
包裹DOM元素的组件使用
```
forwardRef
```
为forwardRef组件设置
```
displayName
```
，便于DevTools调试

State Management

状态管理

Local UI state:
```
useState
```
,
```
useReducer
```
Server state: TanStack Query (
```
useQuery
```
,
```
useMutation
```
)
Shared UI state: React Context with custom hooks
Form state: Controlled components with validation

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

Hooks

Follow Rules of Hooks (top-level, consistent order)
Create custom hooks for reusable logic
Use query key factories for TanStack Query
Memoize expensive computations with
```
useMemo
```
Stabilize callbacks with
```
useCallback
```

遵循Hooks规则（顶层调用、顺序一致）
封装可复用逻辑为自定义Hooks
为TanStack Query使用查询键工厂模式
用
```
useMemo
```
缓存昂贵计算结果
用
```
useCallback
```
稳定回调函数

Styling

样式处理

Use
```
cn()
```
from
```
lib/utils
```
to merge Tailwind classes
Use
```
cva
```
(class-variance-authority) for component variants
Follow dark mode conventions with
```
dark:
```
prefix

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

Related Guides

Quick Reference

快速参考

typescript

// 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
}

typescript

// 合并Tailwind类名的工具函数
import { cn } from '@/lib/utils'
cn('base-class', condition && 'conditional-class', className)

// 查询键工厂模式
export const projectKeys = {
  all: ['projects'] as const,
  lists: () => [...projectKeys.all, 'list'] as const,
  list: (ns: string) => [...projectKeys.lists(), ns] as const,
}

// 带验证的Context Hook
const MyContext = createContext<MyContextType | undefined>(undefined)
export function useMyContext() {
  const ctx = useContext(MyContext)
  if (!ctx) throw new Error('useMyContext必须在MyProvider范围内使用')
  return ctx
}

Testing

测试示例

typescript

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

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

typescript

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

test('渲染组件', () => {
  renderWithProviders(<MyComponent />)
  expect(screen.getByText('Hello')).toBeInTheDocument()
})

react-skills

Original

Translation

React Skills for LlamaFarm Designer

面向LlamaFarm Designer的React技能指南

Tech Stack

技术栈

Directory Structure

目录结构

Core Patterns

核心模式

Component Composition

组件组合

State Management

状态管理

Hooks

Hooks

Styling

样式处理

Related Guides

相关指南

Quick Reference

快速参考

Testing

测试示例