|
| 1 | +--- |
| 2 | +name: code |
| 3 | +description: "Use when writing TypeScript/React code - covers type safety, component patterns, and file organization" |
| 4 | +--- |
| 5 | + |
| 6 | +Source Cursor rule: `.cursor/rules/code.mdc`. |
| 7 | +Original Cursor alwaysApply: `false`. |
| 8 | + |
| 9 | +# Code Standards |
| 10 | + |
| 11 | +## TypeScript |
| 12 | + |
| 13 | +### No `any`, No Unsafe Casts |
| 14 | + |
| 15 | +```tsx |
| 16 | +// ✅ Validate with zod |
| 17 | +const TaskSchema = z.object({ id: z.string(), title: z.string() }); |
| 18 | +const task = TaskSchema.parse(response.data); |
| 19 | + |
| 20 | +// ✅ Use unknown and narrow |
| 21 | +const parseResponse = (data: unknown): Task => { |
| 22 | + if (!isTask(data)) throw new Error('Invalid'); |
| 23 | + return data; |
| 24 | +}; |
| 25 | + |
| 26 | +// ❌ Never |
| 27 | +const data: any = fetchData(); |
| 28 | +const task = response as Task; |
| 29 | +const name = user!.name; |
| 30 | +// @ts-ignore |
| 31 | +``` |
| 32 | + |
| 33 | +### Generics Over Any |
| 34 | + |
| 35 | +```tsx |
| 36 | +// ✅ Generic |
| 37 | +const first = <T>(items: T[]): T | undefined => items[0]; |
| 38 | + |
| 39 | +// ❌ Any |
| 40 | +const first = (items: any[]): any => items[0]; |
| 41 | +``` |
| 42 | + |
| 43 | +## React Patterns |
| 44 | + |
| 45 | +### Named Exports, PascalCase |
| 46 | + |
| 47 | +```tsx |
| 48 | +// ✅ Named export, PascalCase file |
| 49 | +// TaskCard.tsx |
| 50 | +export function TaskCard({ task }: TaskCardProps) { ... } |
| 51 | + |
| 52 | +// ❌ Default export, lowercase |
| 53 | +export default function taskCard() { ... } |
| 54 | +``` |
| 55 | + |
| 56 | +### Derive State, Avoid useEffect |
| 57 | + |
| 58 | +```tsx |
| 59 | +// ✅ Derived |
| 60 | +const completedCount = tasks.filter(t => t.completed).length; |
| 61 | + |
| 62 | +// ❌ Synced state |
| 63 | +const [count, setCount] = useState(0); |
| 64 | +useEffect(() => { |
| 65 | + setCount(tasks.filter(t => t.completed).length); |
| 66 | +}, [tasks]); |
| 67 | +``` |
| 68 | + |
| 69 | +### When useEffect IS Appropriate |
| 70 | + |
| 71 | +```tsx |
| 72 | +// External subscriptions |
| 73 | +useEffect(() => { |
| 74 | + const sub = eventSource.subscribe(handler); |
| 75 | + return () => sub.unsubscribe(); |
| 76 | +}, []); |
| 77 | + |
| 78 | +// DOM measurements |
| 79 | +useEffect(() => { |
| 80 | + setHeight(ref.current?.getBoundingClientRect().height); |
| 81 | +}, []); |
| 82 | +``` |
| 83 | + |
| 84 | +### Toasts with Sonner |
| 85 | + |
| 86 | +```tsx |
| 87 | +import { toast } from 'sonner'; |
| 88 | + |
| 89 | +toast.success('Task created'); |
| 90 | +toast.error('Failed to save'); |
| 91 | +toast.promise(saveTask(), { |
| 92 | + loading: 'Saving...', |
| 93 | + success: 'Saved!', |
| 94 | + error: 'Failed', |
| 95 | +}); |
| 96 | +``` |
| 97 | + |
| 98 | +## File Structure |
| 99 | + |
| 100 | +### Colocate at Route Level |
| 101 | + |
| 102 | +``` |
| 103 | +app/(app)/[orgId]/tasks/ |
| 104 | +├── page.tsx # Server component |
| 105 | +├── components/ |
| 106 | +│ └── TaskList.tsx # Client component |
| 107 | +├── hooks/ |
| 108 | +│ └── useTasks.ts # SWR hook |
| 109 | +└── data/ |
| 110 | + └── queries.ts # Server queries |
| 111 | +``` |
| 112 | + |
| 113 | +### Share Only When Reused 3+ Times |
| 114 | + |
| 115 | +``` |
| 116 | +src/components/shared/ # Cross-page components |
| 117 | +src/hooks/ # Shared hooks (useApiSWR, useDebounce) |
| 118 | +``` |
| 119 | + |
| 120 | +## Code Quality |
| 121 | + |
| 122 | +### File Size Limit: 300 Lines |
| 123 | + |
| 124 | +Split large files into focused components. |
| 125 | + |
| 126 | +### Named Parameters for 2+ Args |
| 127 | + |
| 128 | +```tsx |
| 129 | +// ✅ Named |
| 130 | +const createTask = ({ title, assigneeId }: CreateTaskParams) => { ... }; |
| 131 | +createTask({ title: 'Review PR', assigneeId: user.id }); |
| 132 | + |
| 133 | +// ❌ Positional |
| 134 | +const createTask = (title: string, assigneeId: string) => { ... }; |
| 135 | +createTask('Review PR', user.id); // What's the 2nd param? |
| 136 | +``` |
| 137 | + |
| 138 | +### Early Returns |
| 139 | + |
| 140 | +```tsx |
| 141 | +// ✅ Early return |
| 142 | +function processTask(task: Task | null) { |
| 143 | + if (!task) return null; |
| 144 | + if (task.deleted) return null; |
| 145 | + return <TaskCard task={task} />; |
| 146 | +} |
| 147 | + |
| 148 | +// ❌ Nested |
| 149 | +function processTask(task) { |
| 150 | + if (task) { |
| 151 | + if (!task.deleted) { |
| 152 | + return <TaskCard task={task} />; |
| 153 | + } |
| 154 | + } |
| 155 | + return null; |
| 156 | +} |
| 157 | +``` |
| 158 | + |
| 159 | +### Event Handler Naming |
| 160 | + |
| 161 | +```tsx |
| 162 | +// ✅ Prefix with "handle" |
| 163 | +const handleClick = () => { ... }; |
| 164 | +const handleSubmit = (e: FormEvent) => { ... }; |
| 165 | +const handleTaskCreate = (task: Task) => { ... }; |
| 166 | +``` |
| 167 | + |
| 168 | +## Accessibility |
| 169 | + |
| 170 | +```tsx |
| 171 | +// Interactive elements need keyboard support |
| 172 | +<div |
| 173 | + role="button" |
| 174 | + tabIndex={0} |
| 175 | + onClick={handleClick} |
| 176 | + onKeyDown={(e) => e.key === 'Enter' && handleClick()} |
| 177 | + aria-label="Delete task" |
| 178 | +> |
| 179 | + <TrashIcon /> |
| 180 | +</div> |
| 181 | + |
| 182 | +// Form inputs need labels |
| 183 | +<label htmlFor="task-name">Task Name</label> |
| 184 | +<input id="task-name" type="text" /> |
| 185 | +``` |
0 commit comments