什么是 React 生产工程化？

React 生产工程化是一项技术方法论，旨在将 React 开发从简单的组件创建转变为严谨的工程学科。通过将这些 Openclaw Skills 集成到您的 AI 智能体中，您可以获得框架选择决策矩阵、状态管理树和性能预算。该方法论超越了基础的 API 参考，为现代 Web 开发提供可操作的决策框架、模板和评分系统。

其核心价值在于能够标准化跨团队的复杂架构决策。无论您是在 Vite、Next.js 或 Remix 之间做出选择，还是决定在哪里存储服务器状态，这些 Openclaw Skills 都能提供逻辑支持，以构建符合最高行业标准、易于维护且高性能的应用。

下载入口:https://github.com/openclaw/skills/tree/main/skills/1kalin/afrexai-react-production

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

React 生产工程化 应用场景

• 使用 16 点架构健康检查对现有 React 代码库进行审计。
• 设计基于功能的项目结构，在不产生循环依赖的情况下扩展至数百个路由。
• 通过为特定任务选择正确的工具（Zustand、TanStack Query 或 Context）来实现类型安全的状态管理。
• 在开发生命周期中自动化性能优化和可访问性检查。
• 使用 React Hook Form 和 Zod 设置生产级表单验证。

1. AI 智能体初始化架构评估，以确定项目规模、框架和当前的痛点。
2. 建立基于功能的结构，隔离功能模块并通过 index 导出定义公共 API。
3. 组件开发遵循严格的组件解剖模板，确保 Hook、派生状态和处理函数得到正确组织。
4. 应用状态管理决策树，有效分离服务器状态与客户端状态。
5. 集成 TypeScript 模式（包括辨别联合类型和品牌类型）以实现最大的类型安全。
6. 工作流以生产部署检查表结束，验证性能预算和可访问性合规性。

React 生产工程化 配置指南

要在您的开发环境中使用这些 Openclaw Skills，请确保您的 AI 智能体可以访问方法论文件。使用以下命令初始化配置：

# 安装 React 生产工程化技能包
npx openclaw install afrexai-react-production

# 运行项目健康检查以基准化当前架构
openclaw run check-health --path ./src

React 生产工程化 数据架构与分类体系

该技能根据结构化生命周期组织数据和元数据。这确保了每次 Openclaw Skills 交互都能产生一致的架构输出。

name: afrexai-react-production
description: Complete methodology for building production-grade React applications with architecture decisions, component design, state management, performance optimization, testing, and deployment.

React Production Engineering

Complete methodology for building production-grade React applications. Covers architecture decisions, component design, state management, performance optimization, testing, and deployment — not just API reference, but engineering methodology with decision frameworks, templates, and scoring systems.

Phase 1: Architecture Assessment

Quick Health Check (score /16)

• Component tree depth < 6 levels (+2)
• No prop drilling past 2 levels (+2)
• Bundle size < 200KB gzipped (+2)
• LCP < 2.5s on 4G (+2)
• Test coverage > 70% on business logic (+2)
• Zero any types in production code (+2)
• No direct DOM manipulation (+2)
• Consistent error boundaries (+2)

Architecture Brief

project:
  name: ""
  type: "" # spa | ssr | hybrid | static
  framework: "" # next | remix | vite-spa | astro
  scale: "" # small (<20 routes) | medium (20-100) | large (100+)
  team_size: "" # solo | small (2-5) | medium (6-15) | large (15+)
current_state:
  react_version: "" # 18 | 19
  typescript: true
  router: "" # react-router | next-app | tanstack-router
  state_management: "" # useState | zustand | jotai | redux | tanstack-query
  styling: "" # tailwind | css-modules | styled-components | vanilla-extract
  testing: "" # vitest | jest | playwright | cypress
  ci_cd: "" # github-actions | gitlab-ci | vercel
pain_points: []
goals: []

Framework Selection Decision Matrix

Decision rules:

1. Dashboard/internal tool with no SEO → Vite SPA
2. Marketing + app hybrid → Next.js
3. Content-first with some interactivity → Astro
4. Web-standards-first, nested layouts → Remix
5. Default for most SaaS products → Next.js

Phase 2: Project Structure & Conventions

Recommended Feature-Based Structure

src/
├── app/                    # Routes/pages (framework-specific)
├── features/               # Feature modules (THE core pattern)
│   ├── auth/
│   │   ├── components/     # Feature-specific components
│   │   ├── hooks/          # Feature-specific hooks
│   │   ├── api/            # API calls & types
│   │   ├── utils/          # Feature utilities
│   │   ├── types.ts        # Feature types
│   │   └── index.ts        # Public API (barrel export)
│   ├── dashboard/
│   └── settings/
├── shared/                 # Cross-feature shared code
│   ├── components/         # Generic UI components
│   │   ├── ui/             # Primitives (Button, Input, Card)
│   │   └── layout/         # Layout components
│   ├── hooks/              # Generic hooks
│   ├── lib/                # Utilities, constants
│   └── types/              # Global types
├── providers/              # Context providers
└── styles/                 # Global styles

7 Structure Rules

1. Feature isolation — features/ never import from other features directly; use shared/ or events
2. Barrel exports — every feature has index.ts that defines its public API
3. Colocation — tests, stories, and styles live next to their component
4. Max file size — 300 lines. If bigger, split
5. Max component size — 50 lines of JSX. If bigger, extract
6. No circular deps — enforce with eslint-plugin-import
7. Types colocated — feature types in feature, shared types in shared/types

Naming Conventions

Components:     PascalCase.tsx       (UserProfile.tsx)
Hooks:          useCamelCase.ts      (useAuth.ts)
Utilities:      camelCase.ts         (formatCurrency.ts)
Types:          PascalCase.ts        (User.ts) or types.ts
Constants:      SCREAMING_SNAKE.ts   (API_ENDPOINTS.ts)
Test files:     *.test.tsx           (UserProfile.test.tsx)
Story files:    *.stories.tsx        (Button.stories.tsx)

Phase 3: Component Design Patterns

Component Anatomy Template

// 1. Imports (grouped: react → third-party → internal → types → styles)
import { useState, useCallback, memo } from 'react'
import { clsx } from 'clsx'
import { Button } from '@/shared/components/ui'
import type { User } from '../types'

// 2. Types (exported for reuse)
export interface UserCardProps {
  user: User
  onEdit?: (id: string) => void
  variant?: 'compact' | 'full'
  className?: string
}

// 3. Component (named export, not default)
export const UserCard = memo(function UserCard({
  user,
  onEdit,
  variant = 'full',
  className,
}: UserCardProps) {
  // 4. Hooks first
  const [isExpanded, setIsExpanded] = useState(false)

  // 5. Derived state (no useEffect for derived!)
  const displayName = `${user.firstName} ${user.lastName}`

  // 6. Handlers (useCallback for passed-down refs)
  const handleEdit = useCallback(() => {
    onEdit?.(user.id)
  }, [onEdit, user.id])

  // 7. Early returns for edge cases
  if (!user) return null

  // 8. JSX (max 50 lines)
  return (
    

      
{displayName}
      {variant === 'full' && 
{user.bio}
}
      {onEdit && Edit}
    
  )
})

Component Composition Patterns

1. Compound Components (for related UI groups)

// Usage: A...
const TabsContext = createContext(null)

export function Tabs({ children, defaultValue }: TabsProps) {
  const [activeTab, setActiveTab] = useState(defaultValue)
  return (
    
      {children}
    
  )
}
Tabs.List = TabsList
Tabs.Tab = TabsTab
Tabs.Panel = TabsPanel

2. Render Props (for flexible rendering logic)

export function DataList({ items, renderItem, renderEmpty }: DataListProps) {
  if (items.length === 0) return renderEmpty?.() ?? 
  return 
{items.map((item, i) => 
{renderItem(item)}
)}
}

3. Higher-Order Components (for cross-cutting concerns — use sparingly)

export function withAuth
(Component: ComponentType
) {
  return function AuthenticatedComponent(props: P) {
    const { user, isLoading } = useAuth()
    if (isLoading) return 
    if (!user) return 
    return 
  }
}

10 Component Rules

1. One component per file — always
2. Named exports — never default exports (refactoring safety)
3. Props interface — always explicit, always exported
4. No business logic in components — extract to hooks
5. No inline styles — use Tailwind classes or CSS modules
6. No string refs — useRef only
7. No index as key — use stable identifiers
8. Memo strategically — not everywhere, only for expensive renders
9. Children over props — prefer composition over configuration
10. Accessible by default — semantic HTML, ARIA when needed

Phase 4: State Management Decision Framework

State Type Decision Tree

Is it server data (from API)?
├─ YES → TanStack Query (or SWR) — NEVER Redux/Zustand for server state
│
└─ NO → Is it shared across features?
    ├─ YES → Is it complex with many actions?
    │   ├─ YES → Zustand (or Redux Toolkit if team knows it)
    │   └─ NO → Jotai (atomic) or Zustand (simple store)
    │
    └─ NO → Is it shared within a feature?
        ├─ YES → Context + useReducer (or Zustand feature store)
        └─ NO → useState / useReducer (component-local)

State Management Comparison

Server State with TanStack Query

// api/users.ts — query key factory pattern
export const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters: Filters) => [...userKeys.lists(), filters] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (id: string) => [...userKeys.details(), id] as const,
}

// hooks/useUsers.ts
export function useUsers(filters: Filters) {
  return useQuery({
    queryKey: userKeys.list(filters),
    queryFn: () => fetchUsers(filters),
    staleTime: 5 * 60 * 1000, // 5 min
    placeholderData: keepPreviousData,
  })
}

export function useUpdateUser() {
  const queryClient = useQueryClient()
  return useMutation({
    mutationFn: updateUser,
    onMutate: async (newUser) => {
      // Optimistic update
      await queryClient.cancelQueries({ queryKey: userKeys.detail(newUser.id) })
      const previous = queryClient.getQueryData(userKeys.detail(newUser.id))
      queryClient.setQueryData(userKeys.detail(newUser.id), newUser)
      return { previous }
    },
    onError: (err, newUser, context) => {
      queryClient.setQueryData(userKeys.detail(newUser.id), context?.previous)
    },
    onSettled: (data, err, variables) => {
      queryClient.invalidateQueries({ queryKey: userKeys.detail(variables.id) })
      queryClient.invalidateQueries({ queryKey: userKeys.lists() })
    },
  })
}

Client State with Zustand

// stores/useUIStore.ts — thin, focused stores
interface UIStore {
  sidebarOpen: boolean
  theme: 'light' | 'dark' | 'system'
  toggleSidebar: () => void
  setTheme: (theme: UIStore['theme']) => void
}

export const useUIStore = create()(
  persist(
    (set) => ({
      sidebarOpen: true,
      theme: 'system',
      toggleSidebar: () => set((s) => ({ sidebarOpen: !s.sidebarOpen })),
      setTheme: (theme) => set({ theme }),
    }),
    { name: 'ui-preferences' }
  )
)

// Usage: const theme = useUIStore((s) => s.theme) — always use selectors!

5 State Management Rules

1. Server state ≠ client state — never mix them in the same store
2. Smallest scope possible — useState > Context > Zustand > Redux
3. No useEffect for derived state — use useMemo or compute inline
4. Selectors always — useStore(s => s.field) not useStore()
5. URL is state — search params, filters, pagination → URL, not React state

Phase 5: Hooks Engineering

Custom Hook Template

// hooks/useDebounce.ts
export function useDebounce(value: T, delayMs: number = 300): T {
  const [debouncedValue, setDebouncedValue] = useState(value)

  useEffect(() => {
    const timer = setTimeout(() => setDebouncedValue(value), delayMs)
    return () => clearTimeout(timer)
  }, [value, delayMs])

  return debouncedValue
}

Essential Custom Hooks Library

Hook Rules (beyond React's rules)

1. One concern per hook — useUserSearch not useEverything
2. Return tuple or object — tuple for 1-2 values, object for 3+
3. Accept options object — useDebounce(value, { delay: 300 }) scales better
4. Handle cleanup — every subscription/timer needs cleanup in useEffect return
5. No hooks in conditions — extract conditional logic into the hook body
6. Test hooks independently — use renderHook from testing-library

Phase 6: TypeScript Integration

Strict Configuration

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    "exactOptionalPropertyTypes": true,
    "forceConsistentCasingInFileNames": true,
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Essential Type Patterns

// 1. Discriminated unions for state machines
type AsyncState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error }

// 2. Polymorphic components
type ButtonProps = {
  as?: C
  variant?: 'primary' | 'secondary'
} & ComponentPropsWithoutRef

export function Button({
  as,
  variant = 'primary',
  ...props
}: ButtonProps) {
  const Component = as || 'button'
  return 
}

// 3. Branded types for IDs
type UserId = string & { __brand: 'UserId' }
type PostId = string & { __brand: 'PostId' }

// 4. Zod for runtime validation
const userSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(['admin', 'user', 'viewer']),
})
type User = z.infer

5 TypeScript Rules

1. Zero any — use unknown and narrow, or generics
2. Zod at boundaries — validate all external data (API, forms, URL params)
3. Discriminated unions over optional fields — { status: 'success'; data: T } not { data?: T; error?: Error }
4. Branded types for IDs — prevent userId being passed where postId expected
5. Satisfies over as — config satisfies Config preserves inference; as Config lies

Phase 7: Performance Optimization

Performance Budget

Optimization Priority Stack

Code Splitting Patterns

// 1. Route-based (automatic with Next.js, manual with React Router)
const Dashboard = lazy(() => import('./features/dashboard'))
const Settings = lazy(() => import('./features/settings'))

// 2. Component-based (heavy components)
const Chart = lazy(() => import('./components/Chart'))
const MarkdownEditor = lazy(() =>
  import('./components/MarkdownEditor').then(m => ({ default: m.MarkdownEditor }))
)

// 3. Library-based (heavy third-party)
const { PDFViewer } = await import('@react-pdf/renderer')

React Compiler (React 19+)

// With React Compiler enabled, manual memo/useMemo/useCallback become unnecessary
// The compiler auto-memoizes. Remove manual optimizations:
// ? const memoized = useMemo(() => expensiveCalc(data), [data])
// ? const memoized = expensiveCalc(data)  // compiler handles it

// Enable in babel config:
// plugins: [['babel-plugin-react-compiler', {}]]

Rendering Performance Rules

1. Never create components inside components — define at module level
2. Never create objects/arrays in JSX — style={{ color: 'red' }} rerenders always
3. Children as props prevent rerender —
4. Key must be stable and unique — not index, not Math.random()
5. Avoid context value churn — memoize provider value or split contexts
6. Profile before optimizing — React DevTools Profiler, not guesswork

Phase 8: Error Handling & Resilience

Error Boundary Architecture

// Three levels of error boundaries:
// 1. App-level (catches everything, shows full-page error)
// 2. Feature-level (isolates feature failures)
// 3. Component-level (for risky widgets — charts, third-party)

// Modern error boundary with react-error-boundary
import { ErrorBoundary, FallbackProps } from 'react-error-boundary'

function FeatureErrorFallback({ error, resetErrorBoundary }: FallbackProps) {
  return (
    

      
Something went wrong
      
{error.message}
      Try again
    
  )
}

// Usage:
 queryClient.clear()}>
  

Error Handling Checklist

• App-level error boundary wrapping entire app
• Feature-level boundaries for each major feature
• API errors handled in TanStack Query's onError / error states
• Form validation errors shown inline (not alerts)
• 404 page for unknown routes
• Offline detection and graceful degradation
• Error reporting to monitoring (Sentry, etc.)
• User-friendly error messages (no stack traces in production)

Phase 9: Forms & Validation

Form Library Decision

Default recommendation: React Hook Form + Zod

Form Pattern

const schema = z.object({
  email: z.string().email('Invalid email'),
  password: z.string().min(8, 'Min 8 characters'),
  role: z.enum(['admin', 'user']),
})
type FormData = z.infer

export function LoginForm({ onSubmit }: { onSubmit: (data: FormData) => void }) {
  const form = useForm({
    resolver: zodResolver(schema),
    defaultValues: { email: '', password: '', role: 'user' },
  })

  return (
    

      Email
      
      {form.formState.errors.email && (
        
{form.formState.errors.email.message}
      )}
      {/* ... more fields */}
      
        {form.formState.isSubmitting ? 'Signing in...' : 'Sign in'}
      
    
  )
}

Phase 10: Testing Strategy

Test Pyramid for React

Testing Patterns

// Component test (Testing Library philosophy: test behavior, not implementation)
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'

describe('UserCard', () => {
  it('calls onEdit when edit button clicked', async () => {
    const user = userEvent.setup()
    const onEdit = vi.fn()
    render()

    await user.click(screen.getByRole('button', { name: /edit/i }))
    expect(onEdit).toHaveBeenCalledWith(mockUser.id)
  })

  it('does not render edit button when onEdit not provided', () => {
    render()
    expect(screen.queryByRole('button', { name: /edit/i })).not.toBeInTheDocument()
  })
})

7 Testing Rules

1. Test behavior, not implementation — never test state directly or useEffect
2. Use accessible queries — getByRole > getByTestId > getByText
3. User events over fireEvent — userEvent.click simulates real interaction
4. One assertion per concept — not one per test, but focused assertions
5. Mock at boundaries — API calls, not internal functions
6. No snapshot tests — they break on every change and test nothing meaningful
7. Arrange-Act-Assert — clear structure in every test

Phase 11: Accessibility (a11y)

10-Point Accessibility Checklist

1. Semantic HTML — not
   ,
2. Keyboard navigation — every interactive element reachable via Tab, operable via Enter/Space
3. Focus management — visible focus indicator, logical tab order, focus trap in modals
4. Alt text — every has descriptive alt (or alt="" if decorative)
5. Color contrast — 4.5:1 for normal text, 3:1 for large text (WCAG AA)
6. ARIA labels — aria-label for icon-only buttons, aria-describedby for hints
7. Live regions — aria-live="polite" for dynamic content (toasts, form errors)
8. Reduced motion — respect prefers-reduced-motion for animations
9. Screen reader testing — test with VoiceOver (Mac) or NVDA (Windows)
10. Automated scanning — axe-core in CI (vitest-axe or @axe-core/playwright)

Phase 12: Production Deployment Checklist

Mandatory (P0)

• TypeScript strict mode, zero errors
• All tests passing
• Bundle analyzed, no unexpected large dependencies
• Error boundaries at app and feature level
• Environment variables validated at build time
• Security headers configured (CSP, HSTS, X-Frame-Options)
• SEO meta tags (title, description, OG tags)
• Analytics/error monitoring integrated
• Performance budget met (LCP < 2.5s)

Recommended (P1)

• Storybook for component library
• Visual regression tests
• a11y automated checks in CI
• Feature flags for risky features
• Preview deployments for PRs
• Bundle size CI check (fail if +10%)

Recommended Stack (2025+)

Quality Scoring (0-100)

Grading: 90+ World-class | 75-89 Production-ready | 60-74 Needs work | <60 Tech debt crisis

10 Common Mistakes

Natural Language Commands

• "Set up a new React project" → Phase 1-2 architecture + structure
• "Review my component" → Phase 3 rules + quality scoring
• "Help me choose state management" → Phase 4 decision tree
• "Optimize performance" → Phase 7 priority stack + profiling
• "Add error handling" → Phase 8 error boundary architecture
• "Build a form" → Phase 9 React Hook Form + Zod pattern
• "Write tests for this component" → Phase 10 testing patterns
• "Check accessibility" → Phase 11 checklist
• "Prepare for production" → Phase 12 deployment checklist
• "Audit my React app" → Full quality scoring across all phases
• "Migrate from class components" → Modern patterns + hooks
• "Upgrade to React 19" → Compiler, Server Components, Actions

? Level Up Your React Development

This skill gives you the methodology. For industry-specific implementation patterns, grab an AfrexAI Context Pack ($47):

• SaaS Context Pack — SaaS-specific React patterns, billing UI, dashboard architecture
• Fintech Context Pack — Financial UI patterns, real-time data, compliance
• Healthcare Context Pack — HIPAA-compliant UI, patient data handling

?? Browse all 10 packs: https://afrexai-cto.github.io/context-packs/

?? More Free Skills by AfrexAI

• afrexai-nextjs-production — Next.js production engineering
• afrexai-vibe-coding — AI-assisted development methodology
• afrexai-technical-seo — SEO for React SPAs and SSR
• afrexai-test-automation-engineering — Complete testing strategy
• afrexai-ui-design-system — Design system architecture