.cursorrules (deprecated)

1# Performance Optimization — Cursor Rules
2# Comprehensive rules for writing performant code across the stack
3 
4## Project Context
5You are working on a performance-sensitive application. The codebase must be efficient
6in terms of response time, memory usage, CPU utilization, and network bandwidth. Every
7code change should consider its performance implications. However, always profile before
8optimizing — never guess where bottlenecks are.
9 
10## Core Principles
11- Measure first, optimize second — use profiling tools, not intuition
12- Optimize the critical path — 80% of time is spent in 20% of code
13- Premature optimization is the root of all evil (but known patterns should be followed)
14- Readability matters — don't sacrifice clarity for marginal gains
15- Set performance budgets and test against them
16 
17## Frontend Performance
18 
19### Loading Performance
20- **Bundle size**: Set budgets (e.g., <200KB JS gzipped for initial load)
21- **Code splitting**: Split by route and load on demand
22- **Tree shaking**: Use ES modules, avoid side effects in imports
23- **Lazy loading**: `React.lazy()`, `defineAsyncComponent()`, dynamic `import()`
24- **Preloading**: Use `<link rel="preload">` for critical resources
25- **Font loading**: Use `font-display: swap`, subset fonts, use `next/font`
26 
27### Image Optimization
28```tsx
29// GOOD — responsive images with lazy loading
30<img
31  src="/images/hero.webp"
32  srcSet="/images/hero-400.webp 400w, /images/hero-800.webp 800w, /images/hero-1200.webp 1200w"
33  sizes="(max-width: 768px) 100vw, 50vw"
34  loading="lazy"
35  decoding="async"
36  alt="Product hero"
37  width={800}
38  height={600}
39/>
40 
41// Or use framework image components
42// Next.js: <Image src="..." width={800} height={600} />
43// Nuxt: <NuxtImg src="..." />
44```
45 
46### Rendering Performance
47- Avoid layout thrashing — batch DOM reads and writes
48- Use `transform` and `opacity` for animations (GPU-accelerated)
49- Use `will-change` sparingly for elements that will animate
50- Use `content-visibility: auto` for off-screen content
51- Debounce scroll/resize handlers (150-300ms)
52- Use `requestAnimationFrame` for visual updates
53- Virtualize long lists (react-window, vue-virtual-scroller)
54 
55### React-Specific
56```tsx
57// Memoize expensive components (only when profiling shows re-render issues)
58const ExpensiveList = React.memo(function ExpensiveList({ items }) {
59  return items.map(item => <ExpensiveItem key={item.id} item={item} />);
60});
61 
62// useMemo for expensive computations
63const sortedItems = useMemo(
64  () => items.slice().sort((a, b) => a.price - b.price),
65  [items]
66);
67 
68// useCallback for stable function references passed to memoized children
69const handleSelect = useCallback((id: string) => {
70  setSelectedId(id);
71}, []);
72 
73// Avoid: creating objects/arrays in render
74// BAD
75<MyComponent style={{ color: 'red' }} options={[1, 2, 3]} />
76// GOOD — lift constants
77const style = { color: 'red' };
78const options = [1, 2, 3];
79<MyComponent style={style} options={options} />
80```
81 
82### Core Web Vitals Targets
83- **LCP** (Largest Contentful Paint): < 2.5s
84- **FID/INP** (Interaction to Next Paint): < 200ms
85- **CLS** (Cumulative Layout Shift): < 0.1
86- **TTFB** (Time to First Byte): < 800ms
87 
88## Backend Performance
89 
90### Database Query Optimization
91```sql
92-- Use EXPLAIN ANALYZE to find slow queries
93EXPLAIN ANALYZE SELECT * FROM orders WHERE user_id = 123 AND status = 'pending';
94 
95-- Add indexes for frequently filtered/sorted columns
96CREATE INDEX idx_orders_user_status ON orders(user_id, status);
97 
98-- Use pagination — never return unbounded results
99SELECT * FROM products WHERE category = 'electronics'
100ORDER BY created_at DESC LIMIT 20 OFFSET 0;
101 
102-- Use EXISTS instead of COUNT for existence checks
103SELECT EXISTS(SELECT 1 FROM users WHERE email = 'test@example.com');
104 
105-- Avoid SELECT * — fetch only needed columns
106SELECT id, name, price FROM products WHERE category = $1;
107```
108 
109### N+1 Query Prevention
110```ts
111// BAD — N+1: 1 query for orders + N queries for users
112const orders = await db.order.findMany();
113for (const order of orders) {
114  order.user = await db.user.findUnique({ where: { id: order.userId } });
115}
116 
117// GOOD — eager loading
118const orders = await db.order.findMany({
119  include: { user: { select: { id: true, name: true } } },
120});
121 
122// GOOD — batch loading
123const orders = await db.order.findMany();
124const userIds = [...new Set(orders.map(o => o.userId))];
125const users = await db.user.findMany({ where: { id: { in: userIds } } });
126const userMap = new Map(users.map(u => [u.id, u]));
127orders.forEach(o => { o.user = userMap.get(o.userId); });
128```
129 
130### Caching Strategy
131```
132Request → CDN Cache → Application Cache → Database Cache → Database
133```
134 
135- **CDN/Edge**: Static assets, public pages (Cache-Control headers)
136- **Application**: Frequently accessed data (Redis, in-memory)
137- **Database**: Query result cache, materialized views
138- **HTTP caching**: `Cache-Control`, `ETag`, `Last-Modified` headers
139 
140### Caching Patterns
141```ts
142// Cache-Aside (Lazy Loading)
143async function getUser(id: string): Promise<User> {
144  const cached = await redis.get(`user:${id}`);
145  if (cached) return JSON.parse(cached);
146 
147  const user = await db.user.findUnique({ where: { id } });
148  if (user) {
149    await redis.setex(`user:${id}`, 3600, JSON.stringify(user)); // 1 hour TTL
150  }
151  return user;
152}
153 
154// Cache invalidation on write
155async function updateUser(id: string, data: UpdateUserInput) {
156  const user = await db.user.update({ where: { id }, data });
157  await redis.del(`user:${id}`); // Invalidate cache
158  return user;
159}
160```
161 
162### Connection Pooling
163- Use connection pools for database connections (don't open/close per request)
164- Size pool appropriately: 2-4x CPU cores for database connections
165- Monitor pool utilization and adjust
166- Set connection timeouts to prevent pool exhaustion
167 
168## API Performance
169- Compress responses (gzip/brotli)
170- Paginate all list endpoints
171- Use GraphQL or sparse fieldsets to avoid over-fetching
172- Batch related API calls where possible
173- Use HTTP/2 for multiplexed requests
174- Implement request deduplication for concurrent identical requests
175 
176## Algorithmic Efficiency
177 
178### Common Patterns
179```ts
180// Use Map/Set for lookups instead of Array.find/includes (O(1) vs O(n))
181// BAD
182const user = users.find(u => u.id === targetId); // O(n)
183 
184// GOOD
185const userMap = new Map(users.map(u => [u.id, u]));
186const user = userMap.get(targetId); // O(1)
187 
188// Use Set for membership checks
189// BAD
190const isAllowed = allowedIds.includes(id); // O(n)
191 
192// GOOD
193const allowedSet = new Set(allowedIds);
194const isAllowed = allowedSet.has(id); // O(1)
195```
196 
197### Avoid Unnecessary Work
198```ts
199// BAD — recomputing on every call
200function getExpensiveData() {
201  return rawData.map(transform).filter(validate).sort(compare);
202}
203 
204// GOOD — compute once, cache result
205let cachedResult: Data[] | null = null;
206function getExpensiveData() {
207  if (!cachedResult) {
208    cachedResult = rawData.map(transform).filter(validate).sort(compare);
209  }
210  return cachedResult;
211}
212```
213 
214## Memory Management
215- Avoid memory leaks: clean up event listeners, timers, subscriptions
216- Use weak references (`WeakMap`, `WeakRef`) for caches of large objects
217- Stream large files instead of loading into memory
218- Paginate large database result sets
219- Profile memory with Chrome DevTools or `process.memoryUsage()`
220- Watch for closure-captured variables keeping objects alive
221 
222## Monitoring and Profiling
223 
224### Tools
225- **Frontend**: Chrome DevTools Performance tab, Lighthouse, WebPageTest
226- **Backend**: Application Performance Monitoring (Datadog, New Relic, OpenTelemetry)
227- **Database**: `EXPLAIN ANALYZE`, `pg_stat_statements`, slow query logs
228- **Node.js**: `--inspect` flag, `clinic.js`, `0x` for flame graphs
229- **Python**: `cProfile`, `py-spy`, `memory_profiler`
230 
231### What to Monitor
232- Response time (p50, p95, p99)
233- Error rate
234- Throughput (requests per second)
235- Database query time and count per request
236- Memory usage over time
237- CPU utilization
238- Cache hit rate
239 
240## Common Pitfalls
241- Optimizing without profiling (solving the wrong problem)
242- Premature optimization at the cost of readability
243- N+1 database queries (most common backend performance issue)
244- Not using indexes on frequently queried columns
245- Loading entire datasets when only a page is needed
246- Missing cache invalidation (stale data)
247- Not compressing API responses
248- Blocking the event loop with synchronous operations (Node.js)
249- Creating objects in hot loops (GC pressure)
250- Not setting memory limits on containers (OOM kills)
251