Performance Optimization

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: performance for comprehensive documentation.

When NOT to Use This Skill

This skill focuses on runtime performance optimization. Do NOT use for:

• Algorithm optimization - Use computer science/data structures fundamentals

• Code readability - Use clean-code skill (don't sacrifice readability for micro-optimizations)

• Build time optimization - Use build tool specific skills (Vite, Webpack, etc.)

• Developer experience - Use DX-focused skills and tooling

• Security hardening - Use security-specific skills (performance != security)

Anti-Patterns

Anti-Pattern Why It's Bad Performance Solution

Premature Optimization Waste time on non-bottlenecks Measure first, optimize bottlenecks only

**SELECT *** Fetches unnecessary data Select only needed columns

N+1 Queries Multiple DB roundtrips Use joins or eager loading

No Caching Repeated expensive computations Cache at appropriate layer (memory, Redis, CDN)

Blocking Operations Holds up main thread Use async/background jobs

Large Bundle Slow initial load Code splitting, lazy loading

No Image Optimization Huge assets over network Compress, modern formats (WebP, AVIF), lazy load

Missing Indexes Full table scans Add indexes on queried columns

Memory Leaks Unbounded growth Clean up listeners, close connections, clear refs

Synchronous I/O Blocks event loop Use async I/O operations

Quick Troubleshooting

Issue Diagnostic Solution

Slow page load Check Network tab Optimize images, enable compression, use CDN

Poor LCP Lighthouse audit Preload critical resources, optimize largest element

High INP Performance profiler Debounce handlers, use web workers, reduce JS

Layout shifts (CLS) Layout Shift Regions Set dimensions on images/embeds, avoid dynamic content

Slow API response APM tools, logging Add database indexes, cache responses, optimize queries

High memory usage Memory profiler Fix leaks, clear intervals/listeners, use weak refs

Large bundle Bundle analyzer Code split, tree shake, lazy load routes

Slow database query EXPLAIN ANALYZE Add indexes, rewrite query, partition table

Frontend Performance

Core Web Vitals

Metric Target Measurement

LCP (Largest Contentful Paint) < 2.5s Largest visible element

INP (Interaction to Next Paint) < 200ms Input responsiveness

CLS (Cumulative Layout Shift) < 0.1 Visual stability

Optimization Techniques

// Code splitting const Dashboard = lazy(() => import('./Dashboard'));

// Image optimization <Image src="/hero.jpg" width={1200} height={600} priority // Above fold placeholder="blur" />

// Memoization const MemoizedComponent = memo(ExpensiveComponent); const memoizedValue = useMemo(() => computeExpensive(a, b), [a, b]); const memoizedFn = useCallback(() => handleClick(id), [id]);

// Virtual lists for long lists <VirtualList items={items} itemHeight={50} />

Backend Performance

// N+1 prevention const usersWithPosts = await prisma.user.findMany({ include: { posts: true } // Single query with join });

// Caching const cached = await redis.get(key); if (cached) return JSON.parse(cached); const data = await db.query(); await redis.setex(key, 3600, JSON.stringify(data));

// Connection pooling const pool = new Pool({ max: 20 });

// Async processing await queue.add('sendEmail', { userId });

Database Performance

-- Use EXPLAIN ANALYZE EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'x';

-- Add indexes for frequently queried columns CREATE INDEX idx_users_email ON users(email);

-- Partial indexes CREATE INDEX idx_active_users ON users(email) WHERE is_active = true;

-- Avoid SELECT * SELECT id, name, email FROM users;

-- Pagination SELECT * FROM users ORDER BY id LIMIT 20 OFFSET 0;

Checklist

Area Check

Images Optimized, lazy loaded, proper format

JS Bundle Code split, tree shaken, minified

CSS Critical CSS inline, unused removed

Fonts Preloaded, subset, font-display

Caching CDN, browser cache, API cache

Database Indexes, query optimization

Production Readiness

Monitoring Setup

// Web Vitals reporting import { onCLS, onINP, onLCP, onFCP, onTTFB } from 'web-vitals';

function sendToAnalytics(metric: Metric) { const body = JSON.stringify({ name: metric.name, value: metric.value, id: metric.id, page: window.location.pathname, });

// Use sendBeacon for reliability navigator.sendBeacon('/analytics', body); }

onCLS(sendToAnalytics); onINP(sendToAnalytics); onLCP(sendToAnalytics); onFCP(sendToAnalytics); onTTFB(sendToAnalytics);

Performance Budget

// webpack.config.js or vite.config.ts { performance: { maxAssetSize: 250000, // 250KB maxEntrypointSize: 500000, // 500KB hints: 'error', }, }

// Lighthouse CI budget // lighthouserc.js module.exports = { ci: { collect: { url: ['http://localhost:3000/'], }, assert: { assertions: { 'categories:performance': ['error', { minScore: 0.9 }], 'first-contentful-paint': ['error', { maxNumericValue: 2000 }], 'largest-contentful-paint': ['error', { maxNumericValue: 2500 }], 'cumulative-layout-shift': ['error', { maxNumericValue: 0.1 }], 'total-blocking-time': ['error', { maxNumericValue: 300 }], }, }, }, };

Backend Optimization

// Response compression import compression from 'compression'; app.use(compression({ threshold: 1024 }));

// Response caching headers function setCacheHeaders(res: Response, maxAge: number) { res.setHeader('Cache-Control', public, max-age=${maxAge}, stale-while-revalidate=${maxAge * 2}); res.setHeader('Vary', 'Accept-Encoding'); }

// Streaming responses async function streamLargeData(res: Response) { const stream = db.users.findMany().cursor();

res.setHeader('Content-Type', 'application/json'); res.write('[');

let first = true; for await (const user of stream) { if (!first) res.write(','); res.write(JSON.stringify(user)); first = false; }

res.write(']'); res.end(); }

// Query optimization const users = await prisma.user.findMany({ select: { id: true, name: true, email: true }, // Only needed fields where: { isActive: true }, take: 20, orderBy: { createdAt: 'desc' }, });

Database Optimization

-- Composite indexes for common queries CREATE INDEX idx_users_active_created ON users(is_active, created_at DESC) WHERE is_active = true;

-- Query analysis EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) SELECT * FROM users WHERE email = 'test@example.com';

-- Connection pooling configuration -- pgbouncer.ini [pgbouncer] pool_mode = transaction default_pool_size = 20 max_client_conn = 100

CI Performance Testing

.github/workflows/performance.yml

name: Performance

on: pull_request: branches: [main]

jobs: lighthouse: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Build
    run: npm run build

  - name: Run Lighthouse CI
    uses: treosh/lighthouse-ci-action@v10
    with:
      configPath: ./lighthouserc.js
      uploadArtifacts: true

bundle-size: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Build
    run: npm run build

  - name: Check bundle size
    uses: siddharthkp/bundlesize@v2
    with:
      files: 'dist/*.js'
      maxSize: '250KB'

Caching Strategy

// Cache layers const cacheStrategy = { // L1: In-memory (fastest, smallest) memory: new LRUCache({ max: 1000, ttl: 60000 }),

// L2: Redis (fast, larger) redis: new Redis({ maxRetriesPerRequest: 3 }),

// L3: CDN (edge caching) cdn: { cacheControl: 'public, max-age=31536000, immutable', // Static assets staleWhileRevalidate: 'public, max-age=60, stale-while-revalidate=600', // API }, };

async function getCachedData<T>(key: string, fetcher: () => Promise<T>): Promise<T> { // Check memory const memoryHit = cacheStrategy.memory.get(key); if (memoryHit) return memoryHit as T;

// Check Redis const redisHit = await cacheStrategy.redis.get(key); if (redisHit) { const data = JSON.parse(redisHit); cacheStrategy.memory.set(key, data); return data; }

// Fetch and cache const data = await fetcher(); cacheStrategy.memory.set(key, data); await cacheStrategy.redis.setex(key, 300, JSON.stringify(data));

return data; }

Monitoring Metrics

Metric Target

LCP < 2.5s

INP < 200ms

CLS < 0.1

TTFB < 200ms

API p95 latency < 500ms

Database query time < 100ms

Cache hit rate

90%

Production Checklist

• Core Web Vitals monitored

• Performance budget set

• Lighthouse CI in pipeline

• Bundle size monitoring

• Image optimization

• Code splitting enabled

• Compression enabled

• Caching strategy defined

• Database indexes optimized

• CDN configured

Reference Documentation

• Bundle Analysis

• Caching Strategies