Performance Optimization

Performance Optimization Rules

1. Core Web Vitals

The three metrics Google uses for page experience ranking.

• INP replaced FID as a Core Web Vital in March 2024
• INP measures total interaction latency (input delay + processing + presentation)
• Measure with field data (CrUX, web-vitals library) and lab data (Lighthouse)

2. Frontend — Bundle Optimization

Code Splitting

• Split by route (most effective for initial load)
• Use dynamic import() for non-critical modules
• Separate vendor chunks from application code

// React route-based splitting
const Dashboard = React.lazy(() => import("./Dashboard"));

<Suspense fallback={<Loading />}>
  <Dashboard />
</Suspense>

Tree Shaking

• Use ES modules (import/export) — CommonJS is not tree-shakeable
• Set "sideEffects": false in package.json
• Avoid barrel files (index.ts re-exports) for large libraries

Bundle Analysis

• Use webpack-bundle-analyzer, source-map-explorer, or vite-bundle-visualizer
• Identify and eliminate duplicate dependencies
• Set performance budgets (see Section 8)

3. Frontend — Image Optimization

<img
  src="hero.webp"
  srcset="hero-480.webp 480w, hero-800.webp 800w, hero-1200.webp 1200w"
  sizes="(max-width: 600px) 480px, (max-width: 1000px) 800px, 1200px"
  width="1200" height="630"
  loading="lazy"
  alt="Hero image"
/>

4. Frontend — Rendering Performance

Minimize Reflow/Repaint

• Batch DOM reads before writes (avoid interleaving)
• Use transform and opacity for animations (GPU-composited, no reflow)
• Use requestAnimationFrame for DOM mutations
• Use content-visibility: auto for offscreen content

List Virtualization

Render only visible items for large lists (1000+ items).

• React: @tanstack/react-virtual, react-window
• Vue: vue-virtual-scroller

Avoid Main Thread Blocking

• Break long tasks (> 50ms) with scheduler.yield() or setTimeout
• Offload heavy computation to Web Workers
• Use requestIdleCallback for non-urgent work

React-Specific

• Use React.memo for expensive components
• Use useMemo/useCallback for referential stability (not premature optimization)
• Avoid creating objects/arrays in render

5. Backend — Database Query Tuning

Index Strategy

• Always use EXPLAIN ANALYZE to verify query plans
• Remove unused indexes (they slow down writes)

N+1 Problem

# BAD: N+1 queries
users = User.query.all()          # 1 query
for user in users:
    print(user.orders)            # N queries

# GOOD: Eager loading
users = User.query.options(joinedload(User.orders)).all()  # 1 query

General Rules

• Select only needed columns (avoid SELECT *)
• Use cursor-based pagination over offset-based for large datasets
• Use prepared statements (security + plan caching)
• Monitor slow query logs

6. Backend — Connection and Response

Connection Pooling

• Reuse database connections instead of creating per request
• Pool size guideline (HikariCP/PostgreSQL): connections = (CPU cores × 2) + effective_spindle_count — adjust for other databases
• Set idle timeout and max lifetime
• Tools: HikariCP (Java), pg-pool (Node.js), PgBouncer (PostgreSQL)

Response Compression

• Apply to text resources (HTML, CSS, JS, JSON, SVG)
• Skip already-compressed formats (JPEG, PNG, WOFF2)
• Pre-compress static assets at build time
• Set Vary: Accept-Encoding header

7. Network — Caching Strategy

Cache-Control Patterns

ETag / Conditional Requests

• Server sends ETag (content hash) with response
• Client sends If-None-Match on subsequent requests
• Server returns 304 Not Modified if unchanged (saves bandwidth)

CDN

• Serve static assets from edge servers
• Use content-hash filenames for cache busting (app.a1b2c3.js)
• Set long max-age + immutable for hashed assets
• Use s-maxage for CDN-specific TTL

Service Worker Caching

For detailed caching patterns, see the caching skill.

8. Performance Budget and CI

Define Budgets

CI Integration

// .lighthouserc.js
module.exports = {
  ci: {
    assert: {
      assertions: {
        "largest-contentful-paint": ["error", { maxNumericValue: 2500 }],
        "interactive": ["error", { maxNumericValue: 3800 }],
        "cumulative-layout-shift": ["error", { maxNumericValue: 0.1 }],
      },
    },
  },
};

Tools for CI:

• Lighthouse CI (lhci): Core Web Vitals assertions
• size-limit: JS cost budget (size + execution time)
• bundlesize: Per-file size limits
• Webpack performance: Asset and entrypoint size hints

9. Measurement Tools

Server-Timing

Server-Timing: db;dur=53, app;dur=47.2, cache;desc="Cache Read";dur=23.2

Exposes server-side metrics in DevTools Network tab. Avoid exposing sensitive internals in production.

10. Common Anti-Patterns

For detailed anti-patterns organized by layer, see references/anti-patterns.md.