1---
2name: performance
3description: Optimize web performance for faster loading and better user experience. Use when asked to "speed up my site", "optimize performance", "reduce load time", "fix slow loading", "improve page speed", or "performance audit".
4license: MIT
5metadata:
6  author: web-quality-skills
7  version: "1.0"
8---
9 
10# Performance optimization
11 
12Deep performance optimization based on Lighthouse performance audits. Focuses on loading speed, runtime efficiency, and resource optimization.
13 
14## How it works
15 
161. Identify performance bottlenecks in code and assets
172. Prioritize by impact on Core Web Vitals
183. Provide specific optimizations with code examples
194. Measure improvement with before/after metrics
20 
21## Performance budget
22 
23| Resource | Budget | Rationale |
24|----------|--------|-----------|
25| Total page weight | < 1.5 MB | 3G loads in ~4s |
26| JavaScript (compressed) | < 300 KB | Parsing + execution time |
27| CSS (compressed) | < 100 KB | Render blocking |
28| Images (above-fold) | < 500 KB | LCP impact |
29| Fonts | < 100 KB | FOIT/FOUT prevention |
30| Third-party | < 200 KB | Uncontrolled latency |
31 
32## Critical rendering path
33 
34### Server response
35* **TTFB < 800ms.** Time to First Byte should be fast. Use CDN, caching, and efficient backends.
36* **Enable compression.** Gzip or Brotli for text assets. Brotli preferred (15-20% smaller).
37* **HTTP/2 or HTTP/3.** Multiplexing reduces connection overhead.
38* **Edge caching.** Cache HTML at CDN edge when possible.
39* **Send Early Hints (HTTP 103) for slow origins.** When the origin needs hundreds of milliseconds to assemble the final response, return a `103 Early Hints` with `Link: </hero.webp>; rel=preload; as=image` (and similar for critical CSS/fonts) so the browser starts fetching before the `200 OK` lands. Cloudflare reports [20–30% LCP improvements](https://blog.cloudflare.com/early-hints-performance/) on image-heavy pages. Requires HTTP/2+ and is supported by Chromium-based browsers; other browsers ignore the 103 and fall through to the 200 — safe to enable. CDNs (Cloudflare, Fastly, Akamai) can synthesize 103s automatically from prior responses; on your own origin, emit them from the same handler that issues the 200.
40 
41### Resource loading
42 
43**Preconnect to required origins:**
44```html
45<link rel="preconnect" href="https://fonts.googleapis.com">
46<link rel="preconnect" href="https://cdn.example.com" crossorigin>
47```
48 
49**Preload critical resources:**
50```html
51<!-- LCP image -->
52<link rel="preload" href="/hero.webp" as="image" fetchpriority="high">
53 
54<!-- Critical font -->
55<link rel="preload" href="/font.woff2" as="font" type="font/woff2" crossorigin>
56```
57 
58**Prerender likely-next navigations** with the [Speculation Rules API](https://developer.chrome.com/docs/web-platform/prerender-pages):
59```html
60<script type="speculationrules">
61{
62  "prerender": [{
63    "where": { "href_matches": "/*" },
64    "eagerness": "moderate"
65  }]
66}
67</script>
68```
69`moderate` triggers after a ~200ms hover — usually intent-correlated, rarely wasted. See [core-web-vitals → LCP](../core-web-vitals/SKILL.md#lcp-largest-contentful-paint) for the full discussion of eagerness tradeoffs and the `prerenderingchange` gating you'll need for analytics.
70 
71**Defer non-critical CSS:**
72```html
73<!-- Critical CSS inlined -->
74<style>/* Above-fold styles */</style>
75 
76<!-- Non-critical CSS -->
77<link rel="preload" href="/styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
78<noscript><link rel="stylesheet" href="/styles.css"></noscript>
79```
80 
81### JavaScript optimization
82 
83**Defer non-essential scripts:**
84```html
85<!-- Parser-blocking (avoid) -->
86<script src="/critical.js"></script>
87 
88<!-- Deferred (preferred) -->
89<script defer src="/app.js"></script>
90 
91<!-- Async (for independent scripts) -->
92<script async src="/analytics.js"></script>
93 
94<!-- Module (deferred by default) -->
95<script type="module" src="/app.mjs"></script>
96```
97 
98**Code splitting patterns:**
99```javascript
100// Route-based splitting
101const Dashboard = lazy(() => import('./Dashboard'));
102 
103// Component-based splitting
104const HeavyChart = lazy(() => import('./HeavyChart'));
105 
106// Feature-based splitting
107if (user.isPremium) {
108  const PremiumFeatures = await import('./PremiumFeatures');
109}
110```
111 
112**Tree shaking best practices:**
113```javascript
114// ❌ Imports entire library
115import _ from 'lodash';
116_.debounce(fn, 300);
117 
118// ✅ Imports only what's needed
119import debounce from 'lodash/debounce';
120debounce(fn, 300);
121```
122 
123## Image optimization
124 
125### Format selection
126| Format | Use case | Browser support |
127|--------|----------|-----------------|
128| AVIF | Photos, best compression | 92%+ |
129| WebP | Photos, good fallback | 97%+ |
130| PNG | Graphics with transparency | Universal |
131| SVG | Icons, logos, illustrations | Universal |
132 
133### Responsive images
134```html
135<picture>
136  <!-- AVIF for modern browsers -->
137  <source 
138    type="image/avif"
139    srcset="hero-400.avif 400w,
140            hero-800.avif 800w,
141            hero-1200.avif 1200w"
142    sizes="(max-width: 600px) 100vw, 50vw">
143  
144  <!-- WebP fallback -->
145  <source 
146    type="image/webp"
147    srcset="hero-400.webp 400w,
148            hero-800.webp 800w,
149            hero-1200.webp 1200w"
150    sizes="(max-width: 600px) 100vw, 50vw">
151  
152  <!-- JPEG fallback -->
153  <img 
154    src="hero-800.jpg"
155    srcset="hero-400.jpg 400w,
156            hero-800.jpg 800w,
157            hero-1200.jpg 1200w"
158    sizes="(max-width: 600px) 100vw, 50vw"
159    width="1200" 
160    height="600"
161    alt="Hero image"
162    loading="lazy"
163    decoding="async">
164</picture>
165```
166 
167### LCP image priority
168```html
169<!-- Above-fold LCP image: eager loading, high priority -->
170<img 
171  src="hero.webp" 
172  fetchpriority="high"
173  loading="eager"
174  decoding="sync"
175  alt="Hero">
176 
177<!-- Below-fold images: lazy loading -->
178<img 
179  src="product.webp" 
180  loading="lazy"
181  decoding="async"
182  alt="Product">
183```
184 
185## Font optimization
186 
187### Loading strategy
188```css
189/* System font stack as fallback */
190body {
191  font-family: 'Custom Font', -apple-system, BlinkMacSystemFont, 
192               'Segoe UI', Roboto, sans-serif;
193}
194 
195/* Prevent invisible text */
196@font-face {
197  font-family: 'Custom Font';
198  src: url('/fonts/custom.woff2') format('woff2');
199  font-display: swap; /* or optional for non-critical */
200  font-weight: 400;
201  font-style: normal;
202  unicode-range: U+0000-00FF; /* Subset to Latin */
203}
204```
205 
206### Preloading critical fonts
207```html
208<link rel="preload" href="/fonts/heading.woff2" as="font" type="font/woff2" crossorigin>
209```
210 
211### Variable fonts
212```css
213/* One file instead of multiple weights */
214@font-face {
215  font-family: 'Inter';
216  src: url('/fonts/Inter-Variable.woff2') format('woff2-variations');
217  font-weight: 100 900;
218  font-display: swap;
219}
220```
221 
222## Caching strategy
223 
224### Cache-Control headers
225```
226# HTML (short or no cache)
227Cache-Control: no-cache, must-revalidate
228 
229# Static assets with hash (immutable)
230Cache-Control: public, max-age=31536000, immutable
231 
232# Static assets without hash
233Cache-Control: public, max-age=86400, stale-while-revalidate=604800
234 
235# API responses
236Cache-Control: private, max-age=0, must-revalidate
237```
238 
239### Service worker caching
240```javascript
241// Cache-first for static assets
242self.addEventListener('fetch', (event) => {
243  if (event.request.destination === 'image' ||
244      event.request.destination === 'style' ||
245      event.request.destination === 'script') {
246    event.respondWith(
247      caches.match(event.request).then((cached) => {
248        return cached || fetch(event.request).then((response) => {
249          const clone = response.clone();
250          caches.open('static-v1').then((cache) => cache.put(event.request, clone));
251          return response;
252        });
253      })
254    );
255  }
256});
257```
258 
259## Runtime performance
260 
261### Avoid layout thrashing
262```javascript
263// ❌ Forces multiple reflows
264elements.forEach(el => {
265  const height = el.offsetHeight; // Read
266  el.style.height = height + 10 + 'px'; // Write
267});
268 
269// ✅ Batch reads, then batch writes
270const heights = elements.map(el => el.offsetHeight); // All reads
271elements.forEach((el, i) => {
272  el.style.height = heights[i] + 10 + 'px'; // All writes
273});
274```
275 
276### Debounce expensive operations
277```javascript
278function debounce(fn, delay) {
279  let timeout;
280  return (...args) => {
281    clearTimeout(timeout);
282    timeout = setTimeout(() => fn(...args), delay);
283  };
284}
285 
286// Debounce scroll/resize handlers
287window.addEventListener('scroll', debounce(handleScroll, 100));
288```
289 
290### Use requestAnimationFrame
291```javascript
292// ❌ May cause jank
293setInterval(animate, 16);
294 
295// ✅ Synced with display refresh
296function animate() {
297  // Animation logic
298  requestAnimationFrame(animate);
299}
300requestAnimationFrame(animate);
301```
302 
303### Virtualize long lists
304```javascript
305// For lists > 100 items, render only visible items
306// Use libraries like react-window, vue-virtual-scroller, or native CSS:
307.virtual-list {
308  content-visibility: auto;
309  contain-intrinsic-size: 0 50px; /* Estimated item height */
310}
311```
312 
313### Smooth navigations with View Transitions
314 
315The [View Transitions API](https://developer.chrome.com/docs/web-platform/view-transitions) lets the browser cross-fade (or custom-animate) between two DOM states using a single GPU-composited snapshot — no double-render, no layout thrash, and the snapshot doesn't count toward CLS.
316 
317**Same-document (SPA-style) — Baseline 2026:**
318```javascript
319// Wrap the DOM mutation that swaps the view
320function navigate(newView) {
321  if (!document.startViewTransition) return swapDOM(newView);
322  document.startViewTransition(() => swapDOM(newView));
323}
324```
325 
326**Cross-document (MPA-style) — Chromium-stable, progressive enhancement elsewhere:**
327```css
328/* On both source and destination pages */
329@view-transition { navigation: auto; }
330```
331That's the entire integration — same-origin navigations now fade automatically. To opt specific elements into shared-element transitions (e.g. a thumbnail expanding into a hero), give them a matching `view-transition-name`:
332```css
333.product-thumb[data-id="42"], .product-hero { view-transition-name: product-42; }
334```
335 
336Pair this with Speculation Rules (above) for instant + animated navigations.
337 
338## Third-party scripts
339 
340### Load strategies
341```javascript
342// ❌ Blocks main thread
343<script src="https://analytics.example.com/script.js"></script>
344 
345// ✅ Async loading
346<script async src="https://analytics.example.com/script.js"></script>
347 
348// ✅ Delay until interaction
349<script>
350document.addEventListener('DOMContentLoaded', () => {
351  const observer = new IntersectionObserver((entries) => {
352    if (entries[0].isIntersecting) {
353      const script = document.createElement('script');
354      script.src = 'https://widget.example.com/embed.js';
355      document.body.appendChild(script);
356      observer.disconnect();
357    }
358  });
359  observer.observe(document.querySelector('#widget-container'));
360});
361</script>
362```
363 
364### Facade pattern
365```html
366<!-- Show static placeholder until interaction -->
367<div class="youtube-facade" 
368     data-video-id="abc123" 
369     onclick="loadYouTube(this)">
370  <img src="/thumbnails/abc123.jpg" alt="Video title">
371  <button aria-label="Play video">▶</button>
372</div>
373```
374 
375## Measurement
376 
377### Key metrics
378| Metric | Target | Tool |
379|--------|--------|------|
380| LCP | < 2.5s | Lighthouse, CrUX |
381| FCP | < 1.8s | Lighthouse |
382| Speed Index | < 3.4s | Lighthouse |
383| TBT | < 200ms | Lighthouse |
384| TTI | < 3.8s | Lighthouse |
385 
386### Testing commands
387```bash
388# Lighthouse CLI
389npx lighthouse https://example.com --output html --output-path report.html
390 
391# Web Vitals library
392import {onLCP, onINP, onCLS} from 'web-vitals';
393onLCP(console.log);
394onINP(console.log);
395onCLS(console.log);
396```
397 
398## References
399 
400For Core Web Vitals specific optimizations, see [Core Web Vitals](../core-web-vitals/SKILL.md).
401