Web Performance Web Performance

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: 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)

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 - React memoization, virtual scrolling, debouncing
• examples/code-splitting.md - Lazy loading, tree shaking, bundle budgets
• examples/web-vitals.md - LCP, INP, CLS patterns and monitoring
• examples/image-optimization.md - Image formats, lazy loading, responsive images
• reference.md - Decision frameworks and anti-patterns

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

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.

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 Layout Shift): < 0.1

Measures visual stability -- prevents unexpected layout shifts.

How to improve: Set explicit image/video dimensions, reserve space for dynamic content (ads, embeds), avoid injecting content above existing content, use font-display: swap with size-adjust.

For detailed examples and monitoring setup, see examples/web-vitals.md.

Pattern 3: Code Splitting and Lazy Loading

Lazy load route components and heavy libraries. Code splitting keeps the initial bundle small by loading code on demand.

import { lazy, Suspense } from 'react';

// Route-based splitting - each route is a separate chunk
const Dashboard = lazy(() => import('./pages/dashboard'));
const Reports = lazy(() => import('./pages/reports'));

export function App() {
  return (
    <Suspense fallback={<PageLoader />}>
      <Routes>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/reports" element={<Reports />} />
      </Routes>
    </Suspense>
  );
}

Why good: Splits bundle by route, loads components on demand, users only download what they navigate to

When to lazy load: Route components, heavy feature modules, modals/dialogs, below-fold content

When NOT to lazy load: Above-fold components, error boundaries, loading states

For tree shaking and bundle enforcement, see examples/code-splitting.md.

Pattern 4: Strategic Memoization

Profile before memoizing. React Compiler (v1.0, Oct 2025) auto-memoizes in most cases. Manual memo only when profiling proves a bottleneck.

// Only memoize when profiling shows > 5ms render time
const EXPENSIVE_RENDER_MS = 5;

// ✅ Expensive calculation with large dataset
const sortedRows = useMemo(
  () => [...rows].sort((a, b) => compareValues(a[sortColumn], b[sortColumn])),
  [rows, sortColumn],
);

// ❌ Trivial calculation - memo overhead exceeds cost
const doubled = useMemo(() => value * 2, [value]);

React Compiler (React 19+): Automatically memoizes components, values, and functions at build time. Manual useMemo/useCallback/React.memo rarely needed. Only add manual memo for: third-party interop, non-pure computations, or when profiling shows the compiler missed an optimization.

For complete memoization patterns, see examples/core.md.

RED FLAGS

High Priority Issues:

• No performance budgets defined -- bundle sizes grow unnoticed, Core Web Vitals degrade
• Memoizing everything without profiling -- adds overhead, increases complexity, premature optimization
• Not lazy loading routes -- massive initial bundles, slow Time to Interactive
• Importing entire libraries (import _ from 'lodash') -- bundles unused code, prevents tree shaking
• Not optimizing images -- images are 50%+ of page weight; modern formats reduce size 30-50%
• Blocking main thread with heavy computation -- causes high INP, use web workers or break up long tasks

Medium Priority Issues:

• Not monitoring Core Web Vitals in production -- lab metrics differ from real users
• Rendering 100+ items without virtualization -- DOM bloat, slow scrolling
• No bundle size enforcement in CI -- regressions slip through code review
• Using CommonJS imports (require()) -- prevents tree shaking

Gotchas & Edge Cases:

• React.memo uses shallow comparison -- deep object props always trigger re-render
• useMemo/useCallback have overhead -- only use for expensive operations (> 5ms)
• React Compiler (v1.0) handles memoization automatically -- manual memo is rarely needed
• Lighthouse scores differ from real users -- always monitor RUM with web-vitals
• Code splitting increases total bundle size slightly (runtime overhead) -- net win for initial load
• Virtual scrolling breaks browser find-in-page (Cmd+F)
• Lazy loading doesn't work in SSR -- components load on client mount
• AVIF support is ~95% (2026) -- always provide WebP fallbacks
• Bundle size budgets should account for gzip/brotli compression

CRITICAL REMINDERS

(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)

Failure to follow these rules will result in slow applications, poor Core Web Vitals, large bundles, and degraded user experience.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.