CLAUDE.md

React + TypeScript Project Guidelines

Overview

Modern React application built with TypeScript, Vite, and TailwindCSS.

Tech Stack

  • Framework: React 18+
  • Language: TypeScript (strict mode)
  • Build Tool: Vite
  • Styling: TailwindCSS
  • State Management: React Query + Zustand
  • Testing: Vitest + React Testing Library
  • Linting: ESLint + Prettier

Development Commands

# Install dependencies
npm install

# Run development server
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Type checking
npm run typecheck

# Linting
npm run lint

# Build for production
npm run build

Project Structure

src/
├── components/       # Reusable UI components
│   ├── ui/          # Base UI primitives
│   └── features/    # Feature-specific components
├── hooks/           # Custom React hooks
├── services/        # API calls and external services
├── stores/          # Zustand stores
├── types/           # TypeScript type definitions
├── utils/           # Helper functions
└── pages/           # Page components (if using router)

Component Guidelines

  • Use functional components with hooks
  • Prefer composition over inheritance
  • Keep components small and focused (< 150 lines)
  • Co-locate related files (component, styles, tests, types)
// Good component structure
interface ButtonProps {
  variant?: 'primary' | 'secondary';
  children: React.ReactNode;
  onClick?: () => void;
}

export function Button({ variant = 'primary', children, onClick }: ButtonProps) {
  return (
    <button className={styles[variant]} onClick={onClick}>
      {children}
    </button>
  );
}

TypeScript Best Practices

  • Enable strict mode in tsconfig.json
  • Avoid any - use unknown if type is truly unknown
  • Define explicit return types for functions
  • Use discriminated unions for complex state
  • Prefer interfaces for object shapes, types for unions

State Management

  • Use React Query for server state (API data)
  • Use Zustand for client state (UI state)
  • Avoid prop drilling - use context or stores
  • Keep state as local as possible

Testing

  • Write tests for user interactions, not implementation
  • Use React Testing Library's queries properly
  • Mock API calls, not internal functions
  • Aim for integration tests over unit tests

Performance

  • Use React.memo sparingly and measure first
  • Lazy load routes and heavy components
  • Use useMemo/useCallback only when necessary
  • Optimize images and assets