react-best-practices（React 最佳实践）

React Best Practices

Overview

Apply modern React patterns to build maintainable, performant, and testable applications. This skill covers React 18/19 features including Server Components, hooks best practices, component composition, error boundaries, Suspense, context optimization, and rendering performance. It complements the senior-frontend skill with React-specific depth.

Announce at start: "I'm using the react-best-practices skill for React-specific patterns."

Phase 1: Analyze Component Requirements

Goal: Understand the component's responsibility and data requirements before coding.

Actions

1. Identify the component's single responsibility
2. Determine data requirements (server vs client data)
3. Choose Server Component (default) or Client Component
4. Identify state management needs
5. Plan error and loading states

Server vs Client Decision Table

STOP — Do NOT proceed to Phase 2 until:

• Component responsibility is defined (single purpose)
• Server vs Client decision is made with rationale
• Data requirements are mapped

Phase 2: Implement with Appropriate Patterns

Goal: Apply the correct React patterns for the component's needs.

Actions

1. Apply appropriate composition pattern
2. Implement hooks correctly
3. Add error boundaries and Suspense
4. Optimize rendering where profiling shows need
5. Write tests that verify behavior

STOP — Do NOT proceed to Phase 3 until:

• Patterns match the component's actual needs
• No unnecessary complexity (no premature optimization)
• Tests cover user-visible behavior

Phase 3: Test and Verify

Goal: Verify component behavior through tests.

Actions

1. Write tests using accessible queries
2. Test user interactions and outcomes
3. Test error and loading states
4. Verify accessibility

Query Priority (React Testing Library)

STOP — Testing complete when:

• User interactions produce expected outcomes
• Error states are tested
• Accessibility checks pass

Hooks Best Practices

useState

// Functional updates for state based on previous state
setCount(prev => prev + 1);

// Lazy initialization for expensive initial values
const [data, setData] = useState(() => computeExpensiveInitialValue());

// Group related state
const [form, setForm] = useState({ name: '', email: '', role: 'user' });

useEffect

Dependency Array Rules

• Include ALL values from component scope that change over time
• Functions inside effect should be defined inside effect or wrapped in useCallback
• Never lie about dependencies (ESLint: react-hooks/exhaustive-deps)

Cleanup Pattern

useEffect(() => {
  const controller = new AbortController();
  async function fetchData() {
    try {
      const res = await fetch(url, { signal: controller.signal });
      const data = await res.json();
      setData(data);
    } catch (e) {
      if (e.name !== 'AbortError') setError(e);
    }
  }
  fetchData();
  return () => controller.abort();
}, [url]);

When NOT to Use useEffect

Custom Hooks Rules

• Name starts with use
• Encapsulate reusable stateful logic
• One hook per concern
• Return object (not array) for > 2 values

function useDebounce<T>(value: T, delay: number): T {
  const [debouncedValue, setDebouncedValue] = useState(value);
  useEffect(() => {
    const timer = setTimeout(() => setDebouncedValue(value), delay);
    return () => clearTimeout(timer);
  }, [value, delay]);
  return debouncedValue;
}

Component Composition Patterns

Compound Components

function Tabs({ children, defaultValue }: TabsProps) {
  const [activeTab, setActiveTab] = useState(defaultValue);
  return (
    <TabsContext.Provider value={{ activeTab, setActiveTab }}>
      <div role="tablist">{children}</div>
    </TabsContext.Provider>
  );
}

Tabs.Tab = function Tab({ value, children }: TabProps) {
  const { activeTab, setActiveTab } = useTabsContext();
  return (
    <button role="tab" aria-selected={activeTab === value} onClick={() => setActiveTab(value)}>
      {children}
    </button>
  );
};

Tabs.Panel = function Panel({ value, children }: PanelProps) {
  const { activeTab } = useTabsContext();
  if (activeTab !== value) return null;
  return <div role="tabpanel">{children}</div>;
};

Composition Decision Table

Slots Pattern

// Prefer composition over props for complex content
// Bad
<Card title="Hello" subtitle="World" icon={<Star />} actions={<Button>Edit</Button>} />

// Good
<Card>
  <Card.Header>
    <Card.Icon><Star /></Card.Icon>
    <Card.Title>Hello</Card.Title>
  </Card.Header>
  <Card.Actions>
    <Button>Edit</Button>
  </Card.Actions>
</Card>

Error Boundaries

Placement Strategy Decision Table

Suspense

// Nested Suspense for granular loading
<Suspense fallback={<PageSkeleton />}>
  <Header />
  <Suspense fallback={<SidebarSkeleton />}>
    <Sidebar />
  </Suspense>
  <Suspense fallback={<ContentSkeleton />}>
    <MainContent />
  </Suspense>
</Suspense>

Context Optimization

Problem: Context causes unnecessary re-renders

Solution Decision Table

Rendering Optimization

Memoization Decision Table

Rule: Profile BEFORE memoizing. Premature memoization is the most common React anti-pattern.

Virtualization

For lists > 100 items:

import { useVirtualizer } from '@tanstack/react-virtual';

Server Component Rules

• Cannot use hooks
• Cannot use browser APIs
• Cannot pass functions as props to Client Components
• CAN import and render Client Components
• CAN pass serializable data to Client Components

// Server Component — fetches data directly
async function UserProfile({ userId }: { userId: string }) {
  const user = await db.user.findUnique({ where: { id: userId } });
  return (
    <div>
      <h1>{user.name}</h1>
      <UserActions userId={userId} /> {/* Client Component child */}
    </div>
  );
}

// Client Component — handles interactivity
'use client';
function UserActions({ userId }: { userId: string }) {
  const [isFollowing, setIsFollowing] = useState(false);
  return <Button onClick={() => toggleFollow(userId)}>Follow</Button>;
}

Anti-Patterns / Common Mistakes

Documentation Lookup (Context7)

Use mcp__context7__resolve-library-id then mcp__context7__query-docs for up-to-date docs. Returned docs override memorized knowledge.

• react — for hooks, context, suspense, server components, or React 19+ changes
• next.js — for App Router patterns, data fetching, or server actions

Integration Points

Skill Type

FLEXIBLE — Apply these patterns based on the specific React version, project structure, and team conventions. The principles are consistent, but implementation details may vary. Always profile before optimizing.