--- name: forge-performance description: Web performance discipline. Core Web Vitals (LCP, INP, CLS), image optimization (modern formats + responsive srcset + lazy loading), JS bundle discipline (code-split + tree-shake), critical CSS, font loading without FOIT/FOUT, prefetching that pays off. Contains paste-ready image and font patterns + bundle audit checklist. Use when building user-facing web UI that should feel fast on real devices. license: MIT --- # forge-performance You are writing web UI that real users will load on real devices over real networks. Default agent-written frontend ships 3MB of JavaScript, 4MB of unoptimized images, and 8 web fonts before the first paint. The Lighthouse score is 38 and the user closes the tab. This skill exists to fix that. The mental model: **performance budgets exist; meet them.** Core Web Vitals are the public scoreboard. Everything below is how to play. ## Quick reference (the things you must never ship) 1. Original-size `.jpg`/`.png` for any image visible above the fold. 2. `` without `width`/`height` or aspect-ratio (causes CLS). 3. `` above-the-fold with `loading="lazy"` (delays LCP). 4. Importing an entire icon library to use 3 icons. 5. Web font without `font-display: swap` (causes FOIT). 6. JavaScript bundle over 200KB gzipped for a typical page. 7. CSS bundle over 50KB unminified for a typical page. 8. `import * as Module from "lib"` in code (defeats tree-shaking). 9. Synchronous third-party scripts in the ``. 10. `setTimeout(..., 0)` to avoid a layout thrash (use rAF or yield). ## Hard rules ### Core Web Vitals targets **1. LCP (Largest Contentful Paint) ≤ 2.5s** on 75th-percentile real user. Usually the hero image or hero text. **2. INP (Interaction to Next Paint) ≤ 200ms.** Worst-case interaction response across the session. **3. CLS (Cumulative Layout Shift) ≤ 0.1.** Visual stability. Measure with field data, not just Lighthouse. Lighthouse simulates a slow CPU at fixed bandwidth; real users are more varied. ### Images **4. Modern formats over JPG/PNG.** AVIF or WebP, falling back to JPG. Saves 30-60% bytes. ```tsx // reference: with format fallbacks ... ``` **5. Responsive `srcset` with `sizes`.** Serve the right resolution for the device. ```tsx ... ``` **6. Above-the-fold images: `loading="eager"` (default) + `fetchpriority="high"`.** Below-the-fold: `loading="lazy"`. ```tsx // hero ... // in-content, below fold ... ``` **7. Always set `width` and `height` (or `aspect-ratio` CSS).** Prevents CLS as the image loads. **8. Use a CDN with on-the-fly transforms.** Cloudflare Images, Vercel Image Optimization, ImageKit, Cloudinary. Lets you serve `?w=400&fm=webp&q=80` instead of pre-generating 100 variants. ### Fonts **9. `font-display: swap` for every web font.** Avoids FOIT (Flash of Invisible Text - blank until font loads). ```css @font-face { font-family: 'Inter'; src: url('/fonts/Inter.woff2') format('woff2'); font-weight: 100 900; font-display: swap; } ``` **10. Preload critical fonts.** The font used by the LCP element. ```html ``` **11. Subset fonts.** Latin-only is 1/10th the size of the full Unicode font. Tools: `glyphhanger`, `fonttools`. **12. Variable fonts > many static fonts.** One variable font file (~120KB) replaces 8 weight/style files (~1MB total). ### JavaScript bundles **13. Code-split at the route level.** Each route loads only its own code. ```tsx // Next.js / React Router code-splitting is automatic for dynamic imports const Settings = lazy(() => import('./Settings')); ``` **14. Lazy-load heavy components below the fold.** A 200KB chart library never loads if the user does not scroll. ```tsx const Chart = lazy(() => import('react-chartjs-2')); function Dashboard() { return ( <> {/* loads immediately */} }> {/* code split */} ); } ``` **15. Tree-shake friendly imports. Never `import *`.** ```ts // BAD: pulls in the whole library, no tree-shaking import * as lodash from 'lodash'; const { debounce } = lodash; // GOOD: only debounce is included in the bundle import debounce from 'lodash/debounce'; // BEST: ESM-native, automatic tree-shaking import { debounce } from 'lodash-es'; ``` **16. Avoid `moment.js` (250KB). Use `date-fns` (~10KB per used function) or `dayjs` (2KB).** **17. Bundle audit before every release.** `next build` + check `.next/analyze`. Or `vite-bundle-visualizer`, `webpack-bundle-analyzer`. ```bash # Next.js ANALYZE=true npm run build # Vite npx vite-bundle-visualizer ``` If your main bundle is >200KB gzipped, find the offender and either lazy-load it or replace it. ### Icons **18. Tree-shakable icon library.** `lucide-react`, `phosphor-react`, `react-icons` (with named imports). Never import the whole package. ```ts // BAD: 500KB import * as Icons from 'lucide-react'; // GOOD: ~2KB total import { Check, X, Search } from 'lucide-react'; ``` ### CSS **19. Critical CSS inline in ``; rest in a stylesheet.** Frameworks like Next.js / Vite handle this; verify it's enabled. **20. Tailwind purges unused classes at build.** `npx tailwindcss --minify` for production. **21. Avoid CSS-in-JS that ships its runtime to the client.** styled-components, emotion at runtime mode add ~30KB. Compile-time options (linaria, panda, vanilla-extract) do not. ### Third-party scripts **22. Defer or async every third-party script.** Synchronous third-party scripts in `` block the parser. ```html ``` **23. Use `next/script` in Next.js with `strategy`.** ```tsx