.cursorrules (deprecated)

1# React + TypeScript — Cursor Rules
2# Comprehensive rules for modern React development with TypeScript
3 
4## Project Context
5You are working on a React application written in TypeScript. The codebase uses
6functional components exclusively, React 18+ features, and strict TypeScript
7configuration. The goal is maintainable, type-safe, and performant UI code.
8 
9## Tech Stack
10- React 18+
11- TypeScript 5+ (strict mode enabled)
12- Vite or Create React App (module bundler)
13- React Router v6+ for routing
14- CSS Modules, Tailwind, or styled-components for styling
15- React Query / TanStack Query for server state
16- Zustand or Context API for client state
17 
18## Coding Style
19 
20### Naming Conventions
21- Components: PascalCase (e.g., `UserProfile`, `DashboardLayout`)
22- Hooks: camelCase with `use` prefix (e.g., `useAuth`, `useFetchUsers`)
23- Utilities/helpers: camelCase (e.g., `formatDate`, `parseQueryString`)
24- Types/Interfaces: PascalCase with descriptive names (e.g., `UserProfile`, `ApiResponse<T>`)
25- Constants: UPPER_SNAKE_CASE (e.g., `MAX_RETRY_COUNT`, `API_BASE_URL`)
26- Event handlers: `handle` prefix (e.g., `handleClick`, `handleSubmit`)
27- Boolean variables: `is`, `has`, `should` prefix (e.g., `isLoading`, `hasError`)
28- Files: kebab-case for utilities, PascalCase for components matching component name
29 
30### File Structure
31- One component per file
32- Co-locate tests: `ComponentName.test.tsx` next to `ComponentName.tsx`
33- Co-locate styles: `ComponentName.module.css` next to component
34- Group by feature, not by type (e.g., `features/auth/` not `components/`, `hooks/`)
35- Index files only for public API of a feature module
36- Shared utilities in `src/lib/` or `src/utils/`
37- Shared types in `src/types/`
38 
39## Component Patterns
40 
41### Prefer
42- Functional components with explicit return types
43- Destructured props with TypeScript interfaces defined above the component
44- Custom hooks to extract complex logic from components
45- Composition over prop drilling — use children and render props
46- Controlled components for forms
47- `React.memo()` only when profiling shows re-render issues
48- Named exports (not default exports) for better refactoring support
49- Early returns for guard clauses in rendering logic
50 
51### Avoid
52- Class components (unless wrapping an error boundary)
53- `any` type — use `unknown` and narrow with type guards
54- Inline styles (use CSS modules or utility classes)
55- Deeply nested ternaries in JSX — extract to variables or sub-components
56- `useEffect` for derived state — compute during render instead
57- Index as key in lists that can reorder
58- Prop spreading (`{...props}`) without explicit typing
59- Direct DOM manipulation — use refs only when necessary
60- Barrel files that re-export everything (causes bundle bloat)
61 
62## TypeScript Patterns
63 
64### Typing Props
65```tsx
66interface UserCardProps {
67  user: User;
68  onSelect: (userId: string) => void;
69  variant?: 'compact' | 'full';
70  className?: string;
71}
72 
73export function UserCard({ user, onSelect, variant = 'full', className }: UserCardProps) {
74  // ...
75}
76```
77 
78### Typing Hooks
79```tsx
80function useToggle(initial = false): [boolean, () => void] {
81  const [value, setValue] = useState(initial);
82  const toggle = useCallback(() => setValue(v => !v), []);
83  return [value, toggle];
84}
85```
86 
87### Discriminated Unions for State
88```tsx
89type AsyncState<T> =
90  | { status: 'idle' }
91  | { status: 'loading' }
92  | { status: 'success'; data: T }
93  | { status: 'error'; error: Error };
94```
95 
96### Generic Components
97```tsx
98interface ListProps<T> {
99  items: T[];
100  renderItem: (item: T) => React.ReactNode;
101  keyExtractor: (item: T) => string;
102}
103```
104 
105## Error Handling
106- Use Error Boundaries for component tree errors
107- Handle async errors in try/catch within hooks or query error callbacks
108- Display user-friendly error messages, log detailed errors to console/service
109- Use `ErrorBoundary` wrapper components per feature area, not one global boundary
110- Type error states explicitly in component state
111 
112## Testing Requirements
113- Test behavior, not implementation details
114- Use React Testing Library (not Enzyme)
115- Test user interactions: click, type, submit
116- Test conditional rendering logic
117- Mock API calls at the network level (MSW preferred)
118- Aim for integration tests over unit tests for components
119- Unit test complex hooks and utility functions independently
120- Name tests descriptively: `it('shows error message when submission fails')`
121 
122## Performance Guidelines
123- Use `React.lazy()` and `Suspense` for route-level code splitting
124- Memoize expensive computations with `useMemo` (only after profiling)
125- Stabilize callback references with `useCallback` when passed to memoized children
126- Virtualize long lists (react-window or react-virtuoso)
127- Avoid creating new objects/arrays in render — lift to constants or useMemo
128- Use React DevTools Profiler before optimizing
129 
130## Common Pitfalls
131- Forgetting dependency arrays in useEffect/useMemo/useCallback
132- Setting state in useEffect that triggers infinite re-renders
133- Not cleaning up subscriptions/timers in useEffect return
134- Using `useEffect` to sync props to state (derive instead)
135- Mutating state directly instead of creating new references
136- Over-fetching data — use pagination or infinite scroll
137- Not handling loading and error states in async operations
138- Ignoring accessibility (see accessibility-a11y.cursorrules for full guide)
139