| name | perf-web-optimization |
| description | Optimize web performance: bundle size, images, caching, lazy loading, and overall page speed. Use when site is slow, reducing bundle size, fixing layout shifts, improving Time to Interactive, or optimizing for Lighthouse scores. Triggers on: web performance, bundle size, page speed, slow site, lazy loading. Do NOT use for Core Web Vitals-specific fixes (use core-web-vitals), running Lighthouse audits (use perf-lighthouse), or Astro-specific optimization (use perf-astro). |
Web Performance Optimization
Systematic approach: Measure → Identify → Prioritize → Implement → Verify.
Target Metrics
| Metric | Good | Needs Work | Poor |
|---|
| LCP | < 2.5s | 2.5-4s | > 4s |
| INP | < 200ms | 200-500ms | > 500ms |
| CLS | < 0.1 | 0.1-0.25 | > 0.25 |
| TTFB | < 800ms | 800ms-1.8s | > 1.8s |
Quick Wins
1. Images (usually biggest impact on LCP)
<img src="/hero.webp" alt="Hero" width="1200" height="600" loading="eager" fetchpriority="high" decoding="async" />
<img src="/product.webp" alt="Product" width="400" height="300" loading="lazy" decoding="async" />
Always set width and height to prevent CLS.
2. Fonts (common LCP/CLS culprit)
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
rel="stylesheet"
href="https://fonts.googleapis.com/css2?family=Inter&display=swap"
media="print"
onload="this.media='all'"
/>
3. Third-party Scripts (common INP killer)
<script>
function loadThirdParty() {
}
;['scroll', 'click', 'touchstart'].forEach((e) => addEventListener(e, loadThirdParty, { once: true, passive: true }))
setTimeout(loadThirdParty, 5000)
</script>
4. Critical CSS
Inline critical CSS in <head>, defer the rest:
<style>
</style>
<link rel="preload" href="/styles.css" as="style" onload="this.rel='stylesheet'" />
Bundle Analysis
npx webpack-bundle-analyzer dist/stats.json
npx vite-bundle-visualizer
npx bundlephobia <package-name>
Common heavy packages to replace:
moment (67KB) → date-fns (12KB) or dayjs (2KB)lodash (72KB) → cherry-pick imports or native methods
Code Splitting Patterns
const Chart = lazy(() => import('./Chart'))
const Admin = dynamic(() => import('./Admin'), { ssr: false })
build: {
rollupOptions: {
output: {
manualChunks: {
vendor: ['react', 'react-dom']
}
}
}
}
Caching Headers
# Static assets (immutable hash in filename)
Cache-Control: public, max-age=31536000, immutable
# HTML (revalidate)
Cache-Control: no-cache
# API responses
Cache-Control: private, max-age=0, must-revalidate
Measurement
For running audits, reading reports, and setting budgets, use the perf-lighthouse skill.
Checklist
Images
JavaScript
CSS
Fonts
Detailed Examples
For in-depth optimization patterns, see:
