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 - 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>
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.memouses shallow comparison -- deep object props always trigger re-renderuseMemo/useCallbackhave 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
</red_flags>
<critical_reminders>
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.
</critical_reminders>