name: performance-tuning description: > Optimizes Core Web Vitals (LCP, INP, CLS), bundle size, rendering strategy, image and font loading, caching, and database query performance for Next.js, Vite, React, and Python backends. Use when optimizing performance, reducing load time, fixing slow pages, analyzing bundle size, or when user mentions performance, speed, Lighthouse, or Web Vitals.

Performance Tuning

Fast apps win. Performance is UX. Performance is SEO. Performance is conversion. Slow kills.

Phase 1: Core Web Vitals Measurement

Targets (2026)

Run:

# Lighthouse audit (local)
npx lighthouse http://localhost:3000 --output json --output-path report.json 2>/dev/null

# Or in Chrome: DevTools → Lighthouse → Analyze page load

Phase 2: Bundle Size Analysis

Run:

# Next.js bundle analysis
ANALYZE=true npm run build 2>/dev/null

# Vite bundle analysis
npx vite-bundle-visualizer 2>/dev/null

# Check largest JS chunks
ls -lhS .next/static/chunks/*.js 2>/dev/null | head -10
ls -lhS dist/assets/*.js 2>/dev/null | head -10

# Find largest dependencies
npx cost-of-modules 2>/dev/null | head -20

# Unused dependencies
npx depcheck 2>/dev/null | head -20

Bundle Size Targets

Common Bloat Sources

Run to detect:

# Tree shaking violations
grep -rn "import .* from 'lodash'" src/ --include="*.ts" --include="*.tsx" 2>/dev/null
grep -rn "require('lodash')" src/ --include="*.ts" --include="*.js" 2>/dev/null

Phase 3: Image & Font Optimization

Run:

# Find large images
find src/ public/ -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" 2>/dev/null | xargs ls -lhS 2>/dev/null | head -20

# Check for next/image usage
grep -rn "next/image\|Image" src/ --include="*.tsx" 2>/dev/null | wc -l

# Check for lazy loading
grep -rn "loading=\"lazy\"\|loading=\"eager\"" src/ --include="*.tsx" 2>/dev/null | wc -l

# Check font loading
grep -rn "next/font\|@font-face\|font-display" src/ app/ --include="*.tsx" --include="*.css" 2>/dev/null

Image Targets

Flag if: images > 200KB, no next/image usage, no font-display: swap.

Phase 4: Rendering Strategy

Decision Tree

Run:

# Check rendering strategy in Next.js
grep -rn "export const dynamic\|export const revalidate\|getStaticProps\|getServerSideProps" app/ src/ --include="*.ts" --include="*.tsx" 2>/dev/null

# Check for code splitting
grep -rn "React.lazy\|dynamic(\|lazy(" src/ --include="*.tsx" --include="*.ts" 2>/dev/null | wc -l

Flag if: no dynamic imports for heavy components, all pages use the same rendering strategy.

Phase 5: Database Query Performance

Run:

# N+1 query patterns (ORM)
grep -rn "findMany\|findAll\|\.all()" src/ lib/ --include="*.ts" --include="*.py" 2>/dev/null
grep -rn "include:\|select:\|prefetch_related\|select_related" src/ lib/ --include="*.ts" --include="*.py" 2>/dev/null

# Missing pagination
grep -rn "take\|limit\|offset\|skip\|paginate\|LIMIT" src/ lib/ --include="*.ts" --include="*.py" 2>/dev/null | wc -l

Flag if: findMany/findAll without include (N+1), no pagination on list queries.

Phase 6: Caching Strategy

Run:

# Check for caching headers
grep -rn "Cache-Control\|s-maxage\|stale-while-revalidate\|unstable_cache" src/ app/ --include="*.ts" --include="*.tsx" 2>/dev/null

# Check for ISR configuration
grep -rn "revalidate" app/ --include="*.ts" --include="*.tsx" 2>/dev/null

Flag if: no caching on static assets, no ISR for dynamic content, no API response caching.

⛔ STOP GATE — Performance

DO NOT mark performance as optimized without:

1. Running Lighthouse or equivalent measurement
2. Showing bundle size analysis results
3. Confirming Core Web Vitals meet "Good" thresholds

Output Format

## Performance Report — [Project Name]

### Current State
| Metric | Score | Target | Gap |
|--------|-------|--------|-----|
| LCP | Xs | < 2.5s | Xs |
| INP | Xms | < 200ms | Xms |
| CLS | X | < 0.1 | X |
| Bundle Size | XKB | < 200KB | XKB |

### Issues Found (Priority Order)
1. 🔴 [Critical — directly impacts user experience]
2. 🟡 [Medium — impacts at scale]
3. 🟢 [Nice to have]

### Optimization Plan
1. [Fix 1] — Expected impact: X
2. [Fix 2] — Expected impact: X