Performance Optimization

intent

performance optimization is a measurement-driven discipline. measure first, identify the actual bottleneck (not the assumed one), fix it, then re-measure to confirm the fix worked. only optimize what data proves matters. premature optimization adds complexity without improving user experience. use this skill when performance requirements exist in the spec, when users report slow behavior, when core web vitals fall below thresholds, or when a change introduced a regression.

inputs

measurement tools (choose based on use case)

• synthetic profiling: chrome devtools performance tab, lighthouse (both CLI and CI modes), chrome devtools MCP
• real user monitoring (RUM): web-vitals library (npm), google crux dashboard for production baselines
• APM tools: application performance monitoring (datadog, new relic, elastic, etc. - optional but recommended for production)
• backend profiling: database query logs with execution time, nodejs/python profilers (clinic.js, py-spy)

performance budgets (thresholds)

• javascript bundle: less than 200KB gzipped (initial load)
• CSS: less than 50KB gzipped
• images: less than 200KB per above-the-fold image
• fonts: less than 100KB total
• API response time: less than 200ms at p95
• time to interactive: less than 3.5s on 4G
• lighthouse performance score: 90 or higher

core web vitals baselines

• LCP (largest contentful paint): good = 2.5s or less, needs improvement = 4.0s or less, poor = over 4.0s
• INP (interaction to next paint): good = 200ms or less, needs improvement = 500ms or less, poor = over 500ms
• CLS (cumulative layout shift): good = 0.1 or less, needs improvement = 0.25 or less, poor = over 0.25

external connections

• CI pipeline: bundlesize, lighthouse CI, or custom performance assertions in github actions/gitlab ci
• monitoring dashboard: APM or custom RUM collection (requires event tracking setup)
• database: read access to query logs and execution plans (for backend profiling)

baseline context

• establish a baseline measurement before making any changes. record the exact conditions (cold cache vs. warm cache, network throttling profile, device hardware, specific command or test run)
• if the baseline is missing, create one first before attempting any optimization

procedure

step 1: measure (establish baseline with real data)

1. identify what is slow using the symptom tree below. match your user complaint (slow page load, sluggish interaction, etc.) to a category.

2. choose measurement method based on symptom type:

   • for frontend: use chrome devtools performance tab to record a trace, or run lighthouse in CI (npx lighthouse <url> --output=json)
   • for backend: add timing logs around database queries and API handlers (e.g., console.time('db-query') and console.timeEnd('db-query'))
   • for RUM: import web-vitals library and log metrics to your monitoring system:

     import { onLCP, onINP, onCLS } from 'web-vitals';
     onLCP(sendToAnalytics);
     onINP(sendToAnalytics);
     onCLS(sendToAnalytics);
     

3. run the measurement in fixed conditions:

   • same device/browser/network profile every time (e.g., "throttled to 4G on a Moto G4")
   • same cache state (cold or warm, consistent across runs)
   • minimum 3 runs to establish variance (run-to-run noise)
   • record the mean and the range (min, max, or standard deviation)

4. output: baseline metrics document with timestamp, conditions, and raw numbers (not smoothed or cherry-picked).

symptom tree (where to start measuring)

what is slow?
├── first page load
│   ├── large bundle? → measure bundle size, check code splitting
│   ├── slow server response? → measure TTFB in devtools network waterfall
│   │   ├── DNS long? → add dns-prefetch / preconnect for known origins
│   │   ├── TCP/TLS long? → enable HTTP/2, check edge deployment, keep-alive
│   │   └── waiting (server) long? → profile backend, check queries and caching
│   └── render-blocking resources? → check network waterfall for CSS/JS blocking
├── interaction feels sluggish
│   ├── UI freezes on click? → profile main thread, look for long tasks (over 50ms)
│   ├── form input lag? → check re-renders, controlled component overhead
│   └── animation jank? → check layout thrashing, forced reflows
├── page after navigation
│   ├── data loading? → measure API response times, check for request waterfalls
│   └── client rendering? → profile component render time, check for N+1 fetches
└── backend / API
    ├── single endpoint slow? → profile database queries, check indexes
    ├── all endpoints slow? → check connection pool, memory, CPU
    └── intermittent slowness? → check for lock contention, GC pauses, external deps

step 2: identify the bottleneck (not assumed)

1. map your symptom to the likely cause table below.

2. gather profiling evidence:

   • frontend: inspect chrome devtools performance trace, check the flame chart for long tasks, look at the network waterfall for blocking resources
   • backend: enable query logging with execution time, run a CPU profiler (e.g., node --prof app.js then node --prof-process isolate-*.log), or use an APM tool to attribute latency to functions
   • database: check the query execution plan (EXPLAIN ANALYZE in postgres, similar in mysql/mongo), look for full table scans, missing indexes, or N+1 patterns

3. narrow to one specific bottleneck. do not attempt to fix multiple issues in one change; each fix must be measurable in isolation.

4. output: bottleneck identification with evidence (e.g., "database query taking 800ms, full table scan on users table, missing index on user_id").

bottleneck reference

frontend symptoms:

• slow LCP (over 2.5s): likely large images, render-blocking CSS/JS, or slow server response
• high CLS (over 0.1): likely images without dimensions, late-loaded content, or font shifts
• poor INP (over 200ms): likely heavy javascript on main thread, large DOM mutations, or unoptimized event handlers
• slow initial load: likely large bundle, many network requests, or inefficient bundling

backend symptoms:

• slow API responses: likely N+1 queries, missing database indexes, or unoptimized query logic
• memory growth over time: likely leaked references, unbounded caches, or large payloads
• CPU spikes: likely synchronous heavy computation or regex backtracking
• high latency with good CPU/memory: likely missing caching, redundant computation, or too many network hops

step 3: fix the bottleneck

implement a fix targeting only the bottleneck identified in step 2. use the anti-pattern reference below as a guide. commit the change with a clear message describing what is being fixed and why (e.g., "add include on user relation to fix N+1 in task list endpoint").

common anti-patterns and fixes

N+1 queries (backend)

// bad: one query per task for the owner
const tasks = await db.tasks.findMany();
for (const task of tasks) {
  task.owner = await db.users.findUnique({ where: { id: task.ownerId } });
}

// good: single query with join/include
const tasks = await db.tasks.findMany({
  include: { owner: true },
});

unbounded data fetching

// bad: fetching all records
const allTasks = await db.tasks.findMany();

// good: paginated with limits
const tasks = await db.tasks.findMany({
  take: 20,
  skip: (page - 1) * 20,
  orderBy: { createdAt: 'desc' },
});

missing image optimization (frontend)

<!-- bad: no dimensions, no format optimization, no priority hint -->
<img src="/hero.jpg" />

<!-- good: hero/LCP image with art direction and resolution switching -->
<picture>
  <!-- mobile: portrait crop (8:10) -->
  <source
    media="(max-width: 767px)"
    srcset="/hero-mobile-400.avif 400w, /hero-mobile-800.avif 800w"
    sizes="100vw"
    width="800"
    height="1000"
    type="image/avif"
  />
  <source
    media="(max-width: 767px)"
    srcset="/hero-mobile-400.webp 400w, /hero-mobile-800.webp 800w"
    sizes="100vw"
    width="800"
    height="1000"
    type="image/webp"
  />
  <!-- desktop: landscape crop (2:1) -->
  <source
    srcset="/hero-800.avif 800w, /hero-1200.avif 1200w, /hero-1600.avif 1600w"
    sizes="(max-width: 1200px) 100vw, 1200px"
    width="1200"
    height="600"
    type="image/avif"
  />
  <source
    srcset="/hero-800.webp 800w, /hero-1200.webp 1200w, /hero-1600.webp 1600w"
    sizes="(max-width: 1200px) 100vw, 1200px"
    width="1200"
    height="600"
    type="image/webp"
  />
  <img
    src="/hero-desktop.jpg"
    width="1200"
    height="600"
    fetchpriority="high"
    alt="Hero image description"
  />
</picture>

<!-- good: below-the-fold image with lazy loading and async decoding -->
<img
  src="/content.webp"
  width="800"
  height="400"
  loading="lazy"
  decoding="async"
  alt="Content image description"
/>

unnecessary re-renders (react)

// bad: creates new object on every render, causing children to re-render
function TaskList() {
  return <TaskFilters options={{ sortBy: 'date', order: 'desc' }} />;
}

// good: stable reference
const DEFAULT_OPTIONS = { sortBy: 'date', order: 'desc' } as const;
function TaskList() {
  return <TaskFilters options={DEFAULT_OPTIONS} />;
}

// use react.memo for expensive components
const TaskItem = React.memo(function TaskItem({ task }: Props) {
  return <div>{/* expensive render */}</div>;
});

// use useMemo for expensive computations (only when profiler shows re-compute is slow)
function TaskStats({ tasks }: Props) {
  const stats = useMemo(() => calculateStats(tasks), [tasks]);
  return <div>{stats.completed} / {stats.total}</div>;
}

large bundle size

// good: dynamic import for heavy, rarely-used features
const ChartLibrary = lazy(() => import('./ChartLibrary'));

// good: route-level code splitting wrapped in Suspense
const SettingsPage = lazy(() => import('./pages/Settings'));

function App() {
  return (
    <Suspense fallback={<Spinner />}>
      <SettingsPage />
    </Suspense>
  );
}

missing caching (backend)

// cache frequently-read, rarely-changed data
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
let cachedConfig: AppConfig | null = null;
let cacheExpiry = 0;

async function getAppConfig(): Promise<AppConfig> {
  if (cachedConfig && Date.now() < cacheExpiry) {
    return cachedConfig;
  }
  cachedConfig = await db.config.findFirst();
  cacheExpiry = Date.now() + CACHE_TTL;
  return cachedConfig;
}

// HTTP caching headers for static assets
app.use('/static', express.static('public', {
  maxAge: '1y',           // Cache for 1 year
  immutable: true,        // Never revalidate (use content hashing in filenames)
}));

// cache-control for API responses
res.set('Cache-Control', 'public, max-age=300'); // 5 minutes

step 4: verify (re-measure the same way)

1. re-run the exact measurement from step 1 under identical conditions (same device, network, cache state, minimum 3 runs).

2. compare the new result against the baseline. do not average across old and new runs; keep them separate.

3. check if the improvement exceeds run-to-run variance. if variance is ±15ms and the improvement is 10ms, that is inside noise and does not count.

4. verify that all tests still pass (do not change tests to hide a regression).

5. output: before/after comparison with raw numbers, variance range, and decision (keep or revert).

step 5: decide (keep or revert)

apply this matrix strictly:

result vs baseline	verdict
past the threshold AND tests green	keep. commit with before/after numbers in the message.
within noise (no measurable change)	revert. neutral changes are a revert.
worse	revert.
improved BUT a test went red	revert. a regression wearing a win's clothing is still a regression.

sunk cost is not a reason to keep a change. if you wrote it and it did not work, revert it. the codebase accretes complexity that never bought anything, and you maintain it forever.

step 6: guard (prevent regression)

1. if the optimization was kept, add a performance assertion in CI:

   • bundle size check: npx bundlesize --config bundlesize.config.json
   • lighthouse CI: npx lhci autorun --config=lighthouserc.json
   • custom RUM threshold: assert that the metric stays below the target in production dashboards

2. log the optimization attempt (keep and reverted alike) in a PERF.md or PR checklist so the same dead idea does not get re-run:

   idea	baseline → result	verdict	why
   memoize row component	INP 240ms → 235ms	reverted	inside noise (±15ms). rows not the bottleneck.
   virtualize list	INP 240ms → 90ms	kept	long tasks gone from trace.
   preconnect to API origin	LCP 2.8s → 2.8s	reverted	already same-origin.

decision points

when to optimize vs. when to skip

• if performance requirements exist in the spec (load time budget, response time SLA), optimize. if monitoring or users report slow behavior, optimize. if core web vitals fall below thresholds, optimize. if a change introduced a regression, optimize.
• if you suspect a problem but have no measurement, measure first before optimizing. do not optimize without data.

synthetic vs. RUM measurement

• if you are detecting regressions in CI or isolating issues in a controlled environment, use synthetic (lighthouse, devtools). synthetic is reproducible and catches breakage fast.
• if you need to validate that a fix actually improved user experience in production, use RUM (web-vitals library, crux). synthetic can improve while RUM stays flat (e.g., a fix that helps cold cache but users mostly hit warm cache).
• best practice: use both. synthetic catches regressions early; RUM validates real-world impact.

cold cache vs. warm cache baseline

• if you measure the baseline on a cold cache and the re-measurement on a warm cache, you measure the cache, not your change. keep conditions identical (both cold or both warm).
• for LCP (first meaningful paint), cold cache is standard. for API response time, use warm cache (user's second+ request). be explicit about which one you chose.

change isolation

• if three optimizations ship together, you get one number and cannot attribute which one worked. measure each in isolation, even if they all land in the same PR. if they must ship together, measure each separately first, then measure the bundle, then verify the bundle result matches the sum of the parts.

noise vs. signal

• if run-to-run variance is ±20ms, a 15ms improvement is not a win, it is a different sample. run the test more times or tighten the conditions (reduce background noise, use a dedicated machine, etc.).
• beat the noise, not just the mean. a statistically significant improvement is one that exceeds the variance band consistently across multiple runs.

correctness gates metrics

• if the optimization requires a test to be changed, skipped, or deleted to pass, revert it. the change broke correctness. metrics do not override correctness.
• an optimization that wins by skipping a validation, caching something that must be fresh, or removing an await that was load-bearing is a regression, not a win.

memoization and useMemo red flags

• react.memo and useMemo are correctness tools first (avoid infinite loops, preserve object identity for hooks), not optimization tools. overusing them adds complexity.
• only apply memoization after profiling shows that re-renders or re-computations are the bottleneck. if you memoize everywhere, you obscure the real bottlenecks and pay maintenance cost for nothing.

output contract

step 1 (measure) deliverable

• baseline metrics document (CSV or JSON) with timestamp, conditions (device, network, cache state), and raw numbers from minimum 3 runs
• example format: { "metric": "LCP", "baseline_mean_ms": 2800, "baseline_min_ms": 2600, "baseline_max_ms": 3100, "conditions": "4G, cold cache, moto g4", "date": "2024-01-15" }

**step 2 (