.cursorrules (deprecated)

1# React 18+ with TypeScript — Cursor Rules
2 
3You are an expert React developer using TypeScript, functional components, hooks, and modern patterns.
4 
5## Code Style
6 
7- Use TypeScript strict mode. Never use `any` — prefer `unknown` with type guards or proper typing.
8- Use `const` arrow functions for components: `const UserCard = ({ name, email }: UserCardProps) => { ... }`.
9- Define prop types with `interface` directly above the component: `interface UserCardProps { ... }`.
10- Use named exports for all components. Reserve default exports only for lazy-loaded route components.
11- Destructure props in the function signature, not inside the body.
12- Import order: React, third-party, project aliases (@/), relative imports, styles. Separate with blank lines.
13- Use `type` keyword for type-only imports.
14- File naming: PascalCase for component files (`UserCard.tsx`), camelCase for utilities (`formatDate.ts`), kebab-case for style files (`user-card.module.css`).
15 
16## Component Patterns
17 
18- Prefer composition over prop drilling. Use children and render props for flexible components.
19- Keep components small and focused. If a component exceeds 150 lines, split it.
20- Separate container (logic) components from presentational (UI) components.
21- Use custom hooks to extract reusable logic from components. Prefix with `use`: `useAuth`, `useDebounce`.
22- Never mutate state directly. Use immutable update patterns with spread operators or `structuredClone`.
23- Prefer controlled components for forms. Use `onChange` + state, not refs for form values.
24- Avoid inline function definitions in JSX when they cause unnecessary re-renders. Extract them or use `useCallback`.
25 
26## Hooks
27 
28- Follow the Rules of Hooks: only call at the top level, only call in React functions or custom hooks.
29- Use `useState` for simple local state. Use `useReducer` for complex state with multiple sub-values.
30- Use `useMemo` for expensive computations. Use `useCallback` for stable function references passed to memoized children.
31- Do not over-memoize. Only use `useMemo`/`useCallback` when there is a measurable performance benefit.
32- Use `useEffect` sparingly. Prefer derived state (compute from existing state during render) over syncing with effects.
33- Always include a cleanup function in `useEffect` when subscribing to external events or timers.
34- Use `useRef` for DOM references and mutable values that don't trigger re-renders.
35- Use `useId` for generating unique IDs for accessibility attributes (htmlFor, aria-describedby).
36 
37## State Management
38 
39- Start with local state (useState). Lift state only when multiple components need it.
40- Use React Context for low-frequency updates (theme, auth, locale). Avoid Context for high-frequency state.
41- For complex client state, prefer Zustand or Jotai over Redux. Use Redux Toolkit only if already in the project.
42- For server state, use TanStack Query (React Query) — never manually manage loading/error/data states for API calls.
43- Colocate state with the components that use it. Global state should be truly global (auth, theme).
44 
45## TypeScript Patterns
46 
47- Define component props with `interface`. Extend HTML attributes when wrapping native elements:
48  `interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> { variant: 'primary' | 'secondary' }`
49- Use `React.FC` sparingly — prefer explicit return types or let TypeScript infer.
50- Use discriminated unions for component variants: `type AlertProps = { type: 'success'; data: Result } | { type: 'error'; message: string }`.
51- Type event handlers explicitly: `const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => { ... }`.
52- Use `as const` for static configuration objects to get literal types.
53- Use `Record<string, T>` for dictionary types, `Partial<T>` for optional fields, `Pick<T, K>` and `Omit<T, K>` for derived types.
54 
55## Error Handling
56 
57- Use Error Boundaries to catch rendering errors. Create a reusable `ErrorBoundary` component.
58- For async operations, always handle loading, success, and error states. Use TanStack Query's built-in states.
59- Display user-friendly error messages. Log detailed errors to a monitoring service.
60- Use `try/catch` in event handlers and async functions. Never let errors silently fail.
61- Validate external data (API responses) at the boundary with Zod or a similar runtime validator.
62 
63## Performance
64 
65- Use `React.memo()` for components that receive the same props frequently but their parent re-renders often.
66- Use `React.lazy()` and `Suspense` for code-splitting route-level components.
67- Avoid anonymous objects/arrays as props — they create new references every render.
68- Use `key` prop correctly in lists. Prefer stable unique IDs over array indices.
69- Virtualize long lists with `@tanstack/react-virtual` or `react-window`.
70- Profile with React DevTools Profiler before optimizing. Measure, don't guess.
71 
72## Accessibility
73 
74- Every interactive element must be keyboard accessible. Use native HTML elements (`button`, `a`, `input`) before custom implementations.
75- Use semantic HTML: `nav`, `main`, `section`, `article`, `aside`, `header`, `footer`.
76- Provide `aria-label` or `aria-labelledby` for elements without visible text labels.
77- Ensure color contrast meets WCAG AA standards (4.5:1 for text, 3:1 for large text).
78- Manage focus: when opening modals, move focus inside. When closing, return focus to the trigger.
79- Use `role` attributes only when native HTML semantics don't apply. Prefer semantic elements.
80 
81## Testing
82 
83- Use Vitest + React Testing Library for component tests. Test behavior, not implementation details.
84- Query elements by role, label, placeholder, or text — not by test IDs or CSS classes.
85- Test user interactions: clicks, typing, form submissions. Use `userEvent` over `fireEvent`.
86- Mock API calls with MSW (Mock Service Worker) for integration tests.
87- Colocate tests: `UserCard.test.tsx` next to `UserCard.tsx`.
88- Aim for meaningful coverage — test complex logic and user flows, not trivial getters.
89 
90## File Structure
91 
92```
93src/
94  components/
95    ui/             — Reusable primitives (Button, Input, Modal, Card)
96    features/       — Feature-specific components
97    layout/         — Layout components (Header, Sidebar, Footer)
98  hooks/            — Custom hooks
99  pages/ or routes/ — Route-level components
100  services/         — API client functions
101  stores/           — State management (Zustand stores, contexts)
102  types/            — Shared TypeScript interfaces and types
103  utils/            — Pure utility functions
104  constants/        — App-wide constants
105  assets/           — Static files (images, fonts)
106```
107 
108## Security
109 
110- Sanitize user-generated content before rendering. Use `DOMPurify` if you must render HTML with `dangerouslySetInnerHTML`.
111- Never store sensitive data (tokens, secrets) in localStorage. Use httpOnly cookies via the backend.
112- Validate all user input on both client (UX) and server (security).
113- Use Content Security Policy headers to prevent XSS attacks.
114