/web-performance-web-performance

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

Web Performance Patterns

> **Quick Guide:** Bundle budgets: < 200KB main bundle gzipped. Core Web Vitals: LCP < 2.5s, INP < 200ms, CLS < 0.1. Profile before optimizing -- measure actual bottlenecks, don't guess. Lazy load routes and heavy libraries. Use React Compiler (React 19+) for automatic memoization; manual memo only when profiling proves a bottleneck. Monitor real users with web-vitals library, not just Lighthouse.

---

<critical_requirements>

CRITICAL: Before Optimizing Performance

**(You MUST profile BEFORE optimizing - measure actual bottlenecks with browser DevTools, framework profiler, or Lighthouse)**

**(You MUST set performance budgets BEFORE building features - bundle size limits and Core Web Vitals targets)**

**(You MUST use named constants for ALL performance thresholds - no magic numbers like `200` or `2.5`)**

**(You MUST monitor Core Web Vitals in production - track LCP, INP, CLS for real users, not just lab metrics)**

**(You MUST lazy load route components and heavy libraries - code splitting prevents large initial bundles)**

</critical_requirements>

---

**Auto-detection:** Core Web Vitals, bundle size optimization, LCP, INP, CLS, lazy loading, code splitting, memoization, React Compiler, performance monitoring, web-vitals library, bundle budget, virtualization, react-window, TanStack Virtual

**When to use:**

• Optimizing Core Web Vitals (LCP < 2.5s, INP < 200ms, CLS < 0.1)
• Setting and enforcing bundle size budgets (< 200KB main bundle)
• Implementing runtime performance patterns (strategic memo, lazy loading, virtualization)
• Monitoring performance with web-vitals library in production
• Code splitting and tree shaking to reduce initial bundle

**When NOT to use:**

• Before measuring (premature optimization adds complexity without benefit)
• For simple components (memoizing cheap renders adds overhead)
• Internal admin tools with < 10 users (ROI too low)
• Prototypes and MVPs (optimize after validating product-market fit)

**Key patterns covered:**

• Core Web Vitals targets and improvement strategies (LCP, INP, CLS)
• Bundle size budgets (< 200KB main, < 500KB total initial load)
• Strategic memoization (profile first; React Compiler handles most cases)
• Code splitting (route-based lazy loading, dynamic imports, tree shaking)
• Image optimization (modern formats, lazy loading, responsive images)

---

**Detailed Resources:**

• [examples/core.md](examples/core.md) - React memoization, virtual scrolling, debouncing
• [examples/code-splitting.md](examples/code-splitting.md) - Lazy loading, tree shaking, bundle budgets
• [examples/web-vitals.md](examples/web-vitals.md) - LCP, INP, CLS patterns and monitoring
• [examples/image-optimization.md](examples/image-optimization.md) - Image formats, lazy loading, responsive images
• [reference.md](reference.md) - Decision frameworks and anti-patterns

---

<philosophy>

Philosophy

Performance is a feature, not an afterthought. Fast applications improve user experience, conversion rates, and SEO rankings. Performance optimization requires measurement before action, budgets before building, and monitoring in production.

**Core principles:**

• **Measure first, optimize second** - Profile actual bottlenecks, don't guess
• **Set budgets early** - Define bundle size limits and Core Web Vitals targets before building
• **Monitor real users** - Lab metrics (Lighthouse) differ from real-world performance (RUM)
• **Optimize strategically** - Memoize expensive operations, not everything
• **Lazy load by default** - Load code when needed, not upfront

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Bundle Size Budgets

Set and enforce bundle size limits to prevent bloat. Main bundle should be < 200KB gzipped for fast downloads on 3G networks.

// constants/bundle-budgets.ts
export const BUNDLE_SIZE_BUDGETS_KB = {
  MAIN_BUNDLE_GZIPPED: 200,
  VENDOR_BUNDLE_GZIPPED: 150,
  ROUTE_BUNDLE_GZIPPED: 100,
  TOTAL_INITIAL_LOAD_GZIPPED: 500,
  MAIN_CSS_GZIPPED: 50,
  CRITICAL_CSS_INLINE: 14, // Fits in first TCP packet
} as const;

**Why these limits:** 200 KB ≈ 1 second download on 3G, faster Time to Interactive (TTI), better mobile performance

**Recommended budgets:**

• **Main bundle**: < 200 KB gzipped
• **Vendor bundle**: < 150 KB gzipped
• **Route bundles**: < 100 KB each gzipped
• **Total initial load**: < 500 KB gzipped
• **Main CSS**: < 50 KB gzipped
• **Critical CSS**: < 14 KB inlined (fits in first TCP packet)

For enforcement examples, see [examples/code-splitting.md](examples/code-splitting.md).

---

Pattern 2: Core Web Vitals Optimization

Optimize for Google's Core Web Vitals: LCP < 2.5s, INP < 200ms, CLS < 0.1. These metrics impact SEO and user experience.

// constants/web-vitals.ts
export const CORE_WEB_VITALS_THRESHOLDS = {
  LCP_SECONDS: 2.5, // Largest Contentful Paint
  INP_MS: 200, // Interaction to Next Paint
  CLS_SCORE: 0.1, // Cumulative Layout Shift
  FCP_SECONDS: 1.8, // First Contentful Paint
  TTI_SECONDS: 3.8, // Time to Interactive
  TBT_MS: 300, // Total Blocking Time
  TTFB_MS: 800, // Time to First Byte
} as const;

LCP (Largest Contentful Paint): < 2.5s

Measures loading performance -- when the largest visible element renders.

**How to improve:** Optimize images (modern formats, preload hero images), minimize render-blocking resources, use CDN for static assets, SSR or SSG for critical content.

INP (Interaction to Next Paint): < 200ms

Measures interactivity across ALL user interactions (replaced FID in March 2024). Includes input delay, processing time, and presentation delay.

**How to improve:** Minimize JavaScript execution time, code split to load less JS upfront, use web workers for heavy computation, break up long tasks (> 50ms) with `scheduler.yield()` or `setTimeout`.

CLS (Cumulative