react-best-practices

React Best Practices

This skill covers React/JSX-specific conventions. It layers on top of typescript-conventions — apply that skill first for naming, type safety, async/await, and module structure; this skill only covers what's different for components.

Deeper reference: frameworks/react/CONVENTIONS.md (full harness conventions), languages/typescript/CONVENTIONS.md.

---

Component naming and file structure

• PascalCase for component names. File name matches the component name.
• Use descriptive, specific names: UserProfileCard, not Card.
• One component per file (unless the secondary component is tightly scoped and unexported).

// Good
export function UserProfileCard({ user }: UserCardProps): JSX.Element {
  return <div>{user.name}</div>;
}
// File: UserProfileCard.tsx

// Bad — too generic, doesn't match file name
export function Card({ user }: { user: User }): JSX.Element { }
// File: card.tsx

---

Props typing

Define prop types explicitly with an interface. Destructure in the signature. Return type annotation (JSX.Element or React.ReactNode) is recommended.

interface UserCardProps {
  user: User;
  onSelect?: (user: User) => void;
}

export function UserCard({ user, onSelect }: UserCardProps): JSX.Element {
  return (
    <button type="button" onClick={() => onSelect?.(user)}>
      {user.name}
    </button>
  );
}

---

Hooks rules

1. Only call hooks at the top level — never inside conditions, loops, or nested functions.
2. Only call hooks from React components or custom hooks.
3. Prefix custom hooks with use: useAuth, useDebounce.

// WRONG: conditional hook call
function Component({ isLoggedIn }: Props) {
  if (isLoggedIn) {
    const user = useUser();  // breaks Rules of Hooks
  }
}

// RIGHT: call unconditionally, use the result conditionally
function Component({ isLoggedIn }: Props) {
  const user = useUser();
  if (!isLoggedIn) return null;
  return <div>{user.name}</div>;
}