AI Coding Instructions for React and TypeScript Projects

## React Components

- Always use functional components with hooks
- Never use class components
- Use named exports, not default exports
- One component per file
- Component file names should be PascalCase (e.g., UserProfile.tsx)

Example structure:
export function UserProfile({ user }: UserProfileProps) {
  return <div>...</div>;
}

## React Hooks

- Prefer useState for simple local state
- Use useReducer for complex state logic
- Extract custom hooks for reusable logic
- Custom hooks must start with "use" prefix
- Always include dependency arrays in useEffect/useMemo/useCallback
- Never ignore exhaustive-deps warnings

Example custom hook:
export function useUser(userId: string) {
  const [user, setUser] = useState<User | null>(null);
  // ...
  return { user, isLoading, error };
}

## Props

- Define props interface above the component
- Name props interfaces as ComponentNameProps
- Destructure props in function signature
- Use children prop type from React.ReactNode

Example:
interface ButtonProps {
  variant: 'primary' | 'secondary';
  onClick: () => void;
  children: React.ReactNode;
}

export function Button({ variant, onClick, children }: ButtonProps) {
  // ...
}

## State Management

- Use React Context for global UI state (theme, auth)
- Use TanStack Query (React Query) for server state
- Keep state as close to usage as possible
- Avoid prop drilling beyond 2 levels—use context or composition

## Styling

- Use Tailwind CSS for all styling
- No inline styles except for dynamic values
- Use cn() utility for conditional classes
- Follow mobile-first responsive design

Example:
<button className={cn(
  "px-4 py-2 rounded-md font-medium",
  variant === "primary" && "bg-blue-500 text-white",
  variant === "secondary" && "bg-gray-200 text-gray-800"
)}>
  {children}
</button>

## TypeScript Types

- Always use explicit types for function parameters
- Always use explicit return types for functions
- Prefer interfaces for object shapes
- Use type for unions, intersections, and primitives
- No `any` type—use `unknown` if type is truly unknown
- Enable strict mode

Example:
interface User {
  id: string;
  name: string;
  email: string;
}

function getUser(id: string): Promise<User> {
  // ...
}

## Null and Undefined

- Use optional chaining (?.) for potentially null values
- Use nullish coalescing (??) instead of || for defaults
- Prefer undefined over null for optional values
- Always handle null cases explicitly

Example:
const userName = user?.name ?? 'Anonymous';

## Generics

- Use generics for reusable type-safe utilities
- Name generic parameters descriptively (T is ok for simple cases)
- Constrain generics when possible

Example:
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

## Enums and Constants

- Prefer const objects over enums for better tree-shaking
- Use as const for literal types

Example:
const Status = {
  Pending: 'pending',
  Active: 'active',
  Completed: 'completed',
} as const;

type Status = typeof Status[keyof typeof Status];

# React/TypeScript Coding Standards

## General

- Use TypeScript for all files (.tsx for components, .ts for utilities)
- Enable strict mode in tsconfig.json
- No console.log in production code (use proper logging)
- No commented-out code in commits

## React Components

- Functional components only, no class components
- Named exports, not default exports
- One component per file, file name matches component name
- Props interface defined above component as ComponentNameProps
- Destructure props in function signature

## Hooks

- Follow Rules of Hooks strictly
- Custom hooks start with "use" prefix
- Always specify dependency arrays
- Use useMemo/useCallback only when necessary (measure first)

## TypeScript

- Explicit types for all function parameters and returns
- Interfaces for object shapes, types for unions
- No `any`—use `unknown` or proper types
- Enable strict null checks

## Styling

- Tailwind CSS for all styles
- Mobile-first responsive design
- Use cn() for conditional classes

## Testing

- Test file next to source: Component.tsx → Component.test.tsx
- Use React Testing Library
- Test behavior, not implementation
- Minimum 80% coverage for new code

## File Structure

src/
├── components/     # Reusable UI components
├── features/       # Feature-specific components
├── hooks/          # Custom hooks
├── lib/            # Utilities and helpers
├── types/          # Shared TypeScript types
└── services/       # API and external services

## React/TypeScript Quick Rules

1. Functional components only (no classes)
2. Named exports (no default exports)
3. Explicit TypeScript types for all parameters and returns
4. No `any` type
5. Tailwind for styling
6. Props interface as ComponentNameProps above component
7. Destructure props in function signature