/web-performance-web-performance

name: web-performance-web-performance
description: Bundle optimization, render performance, Core Web Vitals

Web Performance Patterns

> **Quick Guide:** Three numbers decide whether a page is fast: LCP under 2.5s, INP under 200ms, CLS under 0.1. Bundle size is the lever that moves the first two, so budget it — around 200 KB gzipped for the main bundle — and split by route. Measure before optimising and measure again in production, because a lab score and a real user's session disagree. With the React Compiler enabled, memoisation is automatic; a hand-written `useMemo` needs a profile behind it.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — memoisation, virtual scrolling, debouncing
• [examples/code-splitting.md](examples/code-splitting.md) — lazy routes, dynamic imports, tree shaking, budget enforcement
• [examples/web-vitals.md](examples/web-vitals.md) — LCP, INP and CLS patterns, and field measurement
• [examples/image-optimization.md](examples/image-optimization.md) — formats, responsive sources, lazy loading
• [reference.md](reference.md) — threshold and budget tables, format comparison

---

Which path applies

• **The bundle is the problem** — a slow first load, a large main chunk, a heavy dependency; go to

[examples/code-splitting.md](examples/code-splitting.md).

• **The runtime is the problem** — a janky list, a slow interaction, a re-render storm; go to

[examples/core.md](examples/core.md).

• **Nothing is measured yet** — instrument first, because the two above have different answers and

guessing picks the wrong one; go to [examples/web-vitals.md](examples/web-vitals.md).

---

<critical_requirements>

Before optimising performance

**Profile first, and name the bottleneck before changing anything.** Every optimisation costs readability, and one applied to code that was never slow buys nothing back — a profiler, a bundle analysis, or a field measurement is what turns a guess into a target.

**Write the budgets down before the features.** A bundle limit and Core Web Vitals targets that exist in CI are a decision every future dependency is measured against; added afterwards, they only describe how far past the line you already are.

**Measure real sessions, not just a lab run.** Lab conditions have one device, one network and a cold cache; field data has the distribution of devices your users actually hold, and the two disagree most on exactly the pages that matter.

**Load route code when the route is reached.** Splitting on route boundaries is the single largest reduction available to most applications, because it stops every user paying for the pages they never open.

</critical_requirements>

---

**Auto-detection:** Core Web Vitals, LCP, INP, CLS, TTFB, bundle size, bundle budget, code splitting, lazy loading, tree shaking, memoization, React Compiler, virtualization, virtual scrolling, debounce, throttle, performance budget, field measurement, RUM

**Applies to:**

• Core Web Vitals: what each measures, and what moves it
• Bundle budgets, and enforcing them in CI
• Code splitting, dynamic import and tree shaking
• Render cost: memoisation, virtualisation, debouncing, keeping work off the main thread
• Image weight and format selection

**Handled elsewhere:**

• Bundler configuration — chunking strategy and analysis output belong to whichever bundler is in use; this skill decides what the numbers should be.
• Server response time — TTFB is upstream of everything here, and caching, compression and origin latency are the serving layer's.
• Framework-level rendering — whether a page is server-rendered, streamed or static is a framework decision, and each moves LCP differently.
• Data fetching and caching — a request that repeats needlessly is a fetching-layer concern, though it surfaces here as INP.

---

<philosophy>

Philosophy

Performance work goes wrong in one of two ways: optimising what was never slow, or shipping features against no budget until the page is slow everywhere at once. Both are failures of measurement rather than of technique.

So the order is fixed — budget, then build, then measure, then optimise what the measurement named.

</philosophy>

---

<decision_framework>

Where to spend the effort

Is the problem measured?
├─ NO → Measure it. A profiler for runtime, a bundle report for size,
│        field data for what users actually experience.
└─ YES → Is it load or interaction?
    ├─ Load (LCP, first paint) → How big is the initial download?
    │   ├─ Over budget → Split by route, defer heavy dependencies,
    │   │                 drop or replace the largest one
    │   └─ Within budget → It is the critical path: preload the LCP image,
    │                      remove render-blocking resources, cut TTFB
    └─ Interaction (INP, jank) → What is holding the main thread?
        ├─ A long task → Break it up, or move it to a worker
        ├─ Re-rendering → Profile the tree, then memoise what the profile named
        └─ Too many DOM nodes → Virtualise the list

**Memoise or not:** with the React Compiler the answer is usually "the compiler already did". Without it, memoise a component that re-renders often with unchanged props and costs real time to render — and nothing else, because the comparison itself is not free.

**Virtualise or not:** past roughly a hundred rows the DOM is the cost and virtualisation wins. Below that it loses, and it costs you find-in-page and native scroll anchoring either way.

</decision_framework>

---

<patterns>

Core patterns

Pattern 1: Bundle budgets

Budgets are per artifact and enforced in CI, so a dependency that doubles a chunk fails the pull request rather than being discovered in production.

export const BUNDLE_SIZE_BUDGETS_KB = {
  MAIN_BUNDLE_GZIPPED: 200,
  VENDOR_BUNDLE_GZIPPED: 150,
  ROUTE_BUNDLE_GZIPPED: 100,
  TOTAL_INITIAL_LOAD_GZIPPED: 500,
  CRITICAL_CSS_INLINE: 14, // fits in the first TCP round trip
} as const;

The numbers