web-perf

name	web-perf
description	Diagnose and fix web performance through a disciplined measure-first loop. Forces evidence-based optimization: measure → identify bottleneck → fix ONE thing → re-measure → repeat. Prevents guessing. Use when pages load slowly, user mentions performance, LCP, INP, CLS, lighthouse, bundle size, or "make it faster".

Web Performance Optimization

Persistence

ACTIVE whenever performance is the goal. Never optimize without measuring first. Never declare "faster" without before/after numbers.

The Loop (never skip steps)

1. MEASURE — get baseline numbers (Lighthouse, bundle size, TTFB)
2. IDENTIFY — which metric is worst? (LCP? INP? CLS? TTFB?)
3. DIAGNOSE — what's causing THAT specific metric to be bad?
4. FIX ONE THING — smallest change that moves the needle
5. RE-MEASURE — did the number actually improve? By how much?
6. REPEAT — next worst metric. Never fix two things at once.

Why This Order Matters

Without measuring first: you optimize something that wasn't the bottleneck. Wasted work. Without re-measuring: you "optimized" but might have made it worse (happens more than you think). Fixing two things at once: you don't know which one helped (or hurt).

# Lighthouse CI (if available)
npx lighthouse https://your-site.com --output json --output-path ./lh-report.json

# Bundle analysis (Next.js / Vite / Webpack)
npx next build --analyze  # Next.js
npx vite-bundle-visualizer  # Vite
npx webpack-bundle-analyzer stats.json  # Webpack

Core Web Vitals Targets

Metric	Good	Needs Work	Poor	What It Measures
LCP	< 2.5s	2.5-4.0s	> 4.0s	Largest visible element render time
INP	< 200ms	200-500ms	> 500ms	Responsiveness to user input
CLS	< 0.1	0.1-0.25	> 0.25	Visual stability (layout shifts)

Fix by Metric

LCP (Largest Contentful Paint)

Most common causes and fixes:

1. Render-blocking resources

<!-- BAD: blocks render -->
<link rel="stylesheet" href="styles.css">
<script src="app.js"></script>

<!-- GOOD: non-blocking -->
<link rel="stylesheet" href="critical.css">
<link rel="stylesheet" href="styles.css" media="print" onload="this.media='all'">
<script src="app.js" defer></script>

2. Unoptimized hero image

<!-- BAD -->
<img src="hero.png" width="1920" height="1080">

<!-- GOOD: responsive, modern format, preloaded, sized -->
<link rel="preload" as="image" href="hero.webp" fetchpriority="high">
<img src="hero.webp" width="1920" height="1080" 
     srcset="hero-480.webp 480w, hero-960.webp 960w, hero-1920.webp 1920w"
     sizes="100vw" alt="Hero" fetchpriority="high" decoding="async">

3. Slow server response (TTFB)

Fixes:
- Enable CDN (Cloudflare, Vercel Edge, AWS CloudFront)
- Server-side caching (Redis, in-memory)
- Database query optimization (indexes, connection pooling)
- Reduce redirect chains
- Use HTTP/2 or HTTP/3

4. Client-side rendering bottleneck

Fixes:
- SSR/SSG for above-fold content (Next.js, Nuxt, Astro)
- Stream HTML with React Suspense
- Inline critical CSS (< 14KB)
- Preconnect to required origins

INP (Interaction to Next Paint)

Most common causes and fixes:

1. Long tasks blocking main thread

// BAD: 200ms synchronous work
function handleClick() {
  processLargeDataset(data); // blocks for 200ms
  updateUI();
}

// GOOD: yield to browser between chunks
async function handleClick() {
  for (const chunk of chunks(data, 100)) {
    processChunk(chunk);
    await scheduler.yield(); // let browser paint
  }
  updateUI();
}

2. Heavy event handlers

// BAD: re-render entire list on each keystroke
input.addEventListener('input', () => renderList(filter(items)));

// GOOD: debounce + startTransition
input.addEventListener('input', debounce(() => {
  startTransition(() => renderList(filter(items)));
}, 150));

3. JavaScript bundle too large

Fixes:
- Code split by route (dynamic import)
- Tree-shake unused code
- Replace heavy libraries (moment→dayjs, lodash→lodash-es)
- Defer non-critical JS
- Use web workers for computation

CLS (Cumulative Layout Shift)

Most common causes and fixes:

1. Images without dimensions

<!-- BAD: causes shift when image loads -->
<img src="photo.jpg">

<!-- GOOD: aspect ratio reserved -->
<img src="photo.jpg" width="800" height="600">
<!-- Or with CSS aspect-ratio -->
<img src="photo.jpg" style="aspect-ratio: 4/3; width: 100%">

2. Dynamic content insertion

/* Reserve space for dynamic content (ads, embeds) */
.ad-slot { min-height: 250px; }
.embed-container { aspect-ratio: 16/9; }

3. Web fonts causing FOUT

/* Prevent layout shift from font swap */
@font-face {
  font-family: 'Custom';
  src: url('font.woff2') format('woff2');
  font-display: swap;
  size-adjust: 100.5%; /* match fallback metrics */
  ascent-override: 95%;
  descent-override: 22%;
}

Optimization Checklist

Critical Path

• Inline critical CSS (< 14KB)
• Preload LCP image with fetchpriority="high"
• Preconnect to third-party origins
• Defer non-critical JavaScript
• Remove unused CSS (PurgeCSS / Tailwind purge)

Images

• Use WebP/AVIF format
• Responsive srcset with proper sizes
• Lazy-load below-fold images (loading="lazy")
• Set explicit width/height on all images
• Use CDN for image delivery

JavaScript

• Code-split by route
• Tree-shake (ESM imports only)
• Dynamic import for heavy components
• Web worker for CPU-intensive work
• Remove unused polyfills

Caching

• Immutable assets: Cache-Control: max-age=31536000, immutable
• HTML: Cache-Control: no-cache (revalidate)
• Service Worker for offline + cache-first static assets
• CDN cache with proper purge strategy

Fonts

• Self-host fonts (avoid Google Fonts render-blocking)
• Preload critical font files
• Use font-display: swap with size-adjust
• Subset fonts to required characters only

Framework-Specific

Next.js

// next.config.js optimizations
module.exports = {
  images: { formats: ['image/avif', 'image/webp'] },
  experimental: { optimizeCss: true },
  compiler: { removeConsole: { exclude: ['error'] } }
};

Vite

// vite.config.js
export default {
  build: {
    rollupOptions: { output: { manualChunks: { vendor: ['react', 'react-dom'] } } },
    cssCodeSplit: true,
    minify: 'terser'
  }
};

Common Mistakes

• Optimizing without measuring first (you might fix the wrong thing)
• Adding loading="lazy" to above-fold images (hurts LCP)
• Excessive preloading (everything preloaded = nothing prioritized)
• Client-side rendering when SSR would eliminate the LCP problem entirely
• Focusing on bundle size when the real bottleneck is TTFB
• Using will-change on everything (wastes GPU memory)