pedronauck/react

React Development Guide

This skill provides comprehensive guidelines, patterns, and best practices for React development in this project.

Quick Start

1. Best Practices: For component architecture, state management, and TypeScript integration, read references/best-practices.md
2. Element wrappers: If a component renders a single native element (button, input, a, …), extend that element’s props (React.ComponentProps<"…">) and spread ...props — see Extend native element props below and references/best-practices.md → Extending HTML Elements.
3. useEffect Patterns: For understanding when to use (and avoid) useEffect, read references/useeffect-patterns.md
4. Data Fetching: For TanStack Query patterns, use the tanstack skill
5. Forms: For form handling with TanStack Form, use the tanstack skill

Core Principles

• Functional Components Only: Use functional components exclusively - class components are legacy
• Single Responsibility: Keep components small and focused on a single purpose
• Separation of Concerns: Extract behavior logic into custom hooks, keep components focused on rendering
• Feature-Based Organization: Co-locate related files by feature, not by type
• React 19+ Features: Embrace modern React features (use(), Actions, useOptimistic())

Extend native element props

Default rule for wrappers: whenever a component’s root output is a single native element, its props interface MUST extend that element’s intrinsic props — same contract as shadcn/ui-generated primitives. Callers keep access to aria-*, data-*, onClick, disabled, etc., without bespoke passthrough lists.

Do this:

| Requirement | Detail | | ------------- | ------ | | Base type | interface XProps extends React.ComponentProps<"button"> (or "input", "a", "div", …) | | Spreading | Destructure your custom fields, then {...props} (and merged className) onto the DOM node | | Ref | Use React.forwardRef and the matching element ref type when refs are needed |

interface TextFieldProps extends React.ComponentProps<"input"> {
  label: string;
  error?: string;
}

function TextField({ label, error, className, ...props }: TextFieldProps) {
  return (
    <label className="flex flex-col gap-1">
      <span>{label}</span>
      <input className={cn("rounded border px-2 py-1", error && "border-destructive", className)} {...props} />
      {error ? <span className="text-destructive text-sm">{error}</span> : null}
    </label>
  );
}

Variants + CVA: if you use class-variance-authority, combine intrinsic props with VariantProps<typeof variants> (often extends React.ButtonHTMLAttributes<HTMLButtonElement>). Follow the shadcn skill patterns.

Deep dive: references/best-practices.md → Extending HTML Elements.

Quick Reference Tables

State Management Hierarchy

| Priority | Tool | Use Case | |----------|------|----------| | 1 | useState/useReducer | Component-specific UI state | | 2 | Zustand | Shared client state across components | | 3 | TanStack Query | Server state and data synchronization | | 4 | URL state | Shareable application state (TanStack Router) |

useEffect Decision Tree

| Situation | DON'T | DO | |-----------|-------|-----| | Derived state from props/state | useState + useEffect | Calculate during render | | Expensive calculations | useEffect to cache | useMemo | | Reset state on prop change | useEffect with setState | key prop | | User event responses | useEffect watching state | Event handler directly | | Notify parent of changes | useEffect calling onChange | Call in event handler | | Fetch data | useEffect without cleanup | useEffect with cleanup OR TanStack Query |

When You DO Need Effects

• Synchronizing with external systems (non-React widgets, browser APIs)
• Subscriptions to external stores (use useSyncExternalStore when possible)
• Analytics/logging that runs because component displayed
• Data fetching with proper cleanup (or use TanStack Query)

When You DON'T Need Effects

1. Transforming data for rendering - Calculate at top level, re-runs automatically
2. Handling user events - Use event handlers, you know exactly what happened
3. Deriving state - Just compute it: const fullName = firstName + ' ' + lastName
4. Chaining state updates - Calculate all next state in the event handler

TypeScript Integration

// CORRECT: Type props directly (never use React.FC)
interface BrandButtonProps {
  variant: "primary" | "secondary";
  children: React.ReactNode;
}

function BrandButton({ variant, children }: BrandButtonProps) {
  return <button type="button" className={variant}>{children}</button>;
}

// When wrapping a native element, extend its props — see "Extend native element props" above
interface IconButtonProps extends React.ComponentProps<"button"> {
  icon: React.ReactNode;
}

Custom Hooks Guidelines

• Extract non-visual logic into custom hooks
• Keep hooks focused on single purpose
• Use clear naming: useXxx pattern
• Return arrays for state-like hooks, objects for complex returns

// State-like hook returns array
function useToggle(initial = false) {
  const [value, setValue] = useState(initial);
  const toggle = useCallback(() => setValue((v) => !v), []);
  return [value, toggle] as const;
}

// Complex hook returns object
function useUser(id: string) {
  const query = useQuery({ queryKey: ["user", id], queryFn: () => fetchUser(id) });
  return {
    user: query.data,
    isLoading: query.isLoading,
    error: query.error,
    refetch: query.refetch,
  };
}

Component Architecture Pattern

// CORRECT: Hook handles all logic, component handles rendering
function useIssueSearch(projectId: string) {
  const [query, setQuery] = useState("");
  const [filters, setFilters] = useState<Filters>({});

  const issues = useQuery({
    queryKey: ["issues", projectId, query, filters],
    queryFn: () => searchIssues(projectId, query, filters),
  });

  return {
    query,
    setQuery,
    filters,
    setFilters,
    issues: issues.data ?? [],
    isLoading: issues.isLoading,
  };
}

function IssueList({ projectId }: { projectId: string }) {
  const { query, setQuery, issues, isLoading } = useIssueSearch(projectId);

  return (
    <div>
      <SearchInput value={query} onChange={setQuery} />
      {isLoading ? <Loading /> : <IssueTable issues={issues} />}
    </div>
  );
}

File Naming Conventions

| Type | Pattern | Example | |------|---------|---------| | Components | kebab-case.tsx | user-avatar.tsx | | Hooks | use-kebab-case.ts | use-user-data.ts | | Utilities | camelCase.ts | formatDate.ts | | Types | types.ts | types.ts | | Tests | *.test.tsx | user-avatar.test.tsx |

Testing with Vitest

import { describe, it, expect, vi } from "vitest";
import { render, screen } from "@testing-library/react";
import { renderHook, act } from "@testing-library/react";

describe("MyComponent", () => {
  it("renders correctly", () => {
    render(<MyComponent />);
    expect(screen.getByText("Hello")).toBeInTheDocument();
  });
});

describe("useMyHook", () => {
  it("returns expected value", () => {
    const { result } = renderHook(() => useMyHook());
    expect(result.current.value).toBe(expected);
  });
});

Validation Checklist

Before finishing a task involving React:

• [ ] Components are functional and follow single responsibility principle
• [ ] Behavior logic is extracted into custom hooks
• [ ] TypeScript props are typed directly (not using React.FC); native wrappers extend React.ComponentProps<"…"> (or ButtonHTMLAttributes + variants per shadcn skill) and forward ...props
• [ ] State management follows the hierarchy (local -> Zustand -> TanStack Query -> URL)
• [ ] useEffect is only used for external system synchronization
• [ ] Error boundaries are in place for error handling
• [ ] Loading and error states are handled
• [ ] Accessibility requirements are met (semantic HTML, keyboard navigation)
• [ ] Tests are written for components and hooks
• [ ] Run pnpm run lint, pnpm run typecheck, and pnpm run test

Detailed References

For comprehensive guidance, consult these reference files:

• references/best-practices.md - Component architecture, TypeScript, state management, React 19+ features, testing patterns
• references/useeffect-patterns.md - When to use/avoid useEffect, anti-patterns, and better alternatives