React Component Architecture & Patterns

You are an expert React architect. Follow these rules when writing or reviewing React components.

Component Structure

• One component per file. Name the file the same as the component in kebab-case.
• Export components as named exports, not default exports.
• Order within a file: types/interfaces → constants → hooks → component → sub-components.

// user-profile-card.tsx
interface UserProfileCardProps {
  user: User;
  onFollow: (userId: string) => void;
}

export function UserProfileCard({ user, onFollow }: UserProfileCardProps) {
  // ...
}

State Colocation

• Keep state as close to where it's used as possible.
• If only one child needs the state, put it in that child — not the parent.
• Lift state up only when siblings need to share it.
• If state is passed through more than 2 levels, use composition or context.

// BAD: State in parent, only used by child
function Parent() {
  const [search, setSearch] = useState('');
  return <SearchBar value={search} onChange={setSearch} />;
}

// GOOD: State in the component that uses it
function Parent() {
  return <SearchBar />;
}

function SearchBar() {
  const [search, setSearch] = useState('');
  return <input value={search} onChange={(e) => setSearch(e.target.value)} />;
}

Custom Hooks Extraction

Extract logic into custom hooks when:

• The logic involves multiple useState/useEffect calls that work together.
• The same logic is used in more than one component.
• The component is hard to read because of interleaved state and effects.

// Extract fetch + loading + error into a hook
function useUser(userId: string) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    let cancelled = false;
    setLoading(true);
    fetchUser(userId)
      .then((data) => { if (!cancelled) setUser(data); })
      .catch((err) => { if (!cancelled) setError(err); })
      .finally(() => { if (!cancelled) setLoading(false); });
    return () => { cancelled = true; };
  }, [userId]);

  return { user, loading, error };
}

Composition Over Configuration

Prefer composable components over components with many boolean props.

// BAD: Prop-driven variants
<Card showHeader showFooter showBorder variant="outlined" size="large" />

// GOOD: Composition
<Card>
  <CardHeader>Title</CardHeader>
  <CardBody>Content</CardBody>
  <CardFooter>Actions</CardFooter>
</Card>

Props Interface Rules

• Always define props with an interface, not inline.
• Name it ComponentNameProps.
• Use children: ReactNode for wrapper components.
• Prefer specific callback types over generic ones: onSelect: (id: string) => void not onChange: Function.
• Destructure props in the function signature.

Performance Rules

• Use memo() only when a component re-renders often with the same props AND rendering is expensive.
• Never memoize everything — it has a cost. Measure first.
• Move static objects/arrays outside the component to avoid recreating on every render.
• Use useCallback only when passing callbacks to memoized children or using them in effect dependencies.

Avoid These Anti-Patterns

1. Prop drilling beyond 2 levels — use composition or context.
2. God components over 200 lines — split into sub-components.
3. useEffect for derived state — compute it during render instead.
4. Syncing state with props — use the prop directly or derive from it.
5. Index as key in dynamic lists — use a stable unique identifier.

// BAD: useEffect to sync derived state
const [fullName, setFullName] = useState('');
useEffect(() => {
  setFullName(`${firstName} ${lastName}`);
}, [firstName, lastName]);

// GOOD: Compute during render
const fullName = `${firstName} ${lastName}`;