performance

★ 2,500

by addyosmani · part of addyosmani/web-quality-skills

🔥🔥🔥🔥✓ VerifiedFreeNeeds API keys

🧩 One of 5 skills in the addyosmani/web-quality-skills package — works on its own, and pairs well with its siblings.

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by addyosmani

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". npx skills add https://github.com/addyosmani/web-quality-skills --skill performance Download ZIP GitHub2.5k

Performance optimization

Deep performance optimization based on Lighthouse performance audits. Focuses on loading speed, runtime efficiency, and resource optimization.

How it works

Identify performance bottlenecks in code and assets
Prioritize by impact on Core Web Vitals
Provide specific optimizations with code examples
Measure improvement with before/after metrics

Performance budget

Resource Budget Rationale Total page weight < 1.5 MB 3G loads in ~4s JavaScript (compressed) < 300 KB Parsing + execution time CSS (compressed) < 100 KB Render blocking Images (above-fold) < 500 KB LCP impact Fonts < 100 KB FOIT/FOUT prevention Third-party < 200 KB Uncontrolled latency

Critical rendering path

Server response

TTFB < 800ms. Time to First Byte should be fast. Use CDN, caching, and efficient backends.
Enable compression. Gzip or Brotli for text assets. Brotli preferred (15-20% smaller).
HTTP/2 or HTTP/3. Multiplexing reduces connection overhead.
Edge caching. Cache HTML at CDN edge when possible.
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 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.

Resource loading

Preconnect to required origins:

Copy & paste — that's it


- 

-

Preload critical resources:

Copy & paste — that's it

Prerender likely-next navigations with the Speculation Rules API:

Copy & paste — that's it

 
{
 "prerender": [{
 "where": { "href_matches": "/*" },
 "eagerness": "moderate"
 }]
}

moderate triggers after a ~200ms hover — usually intent-correlated, rarely wasted. See core-web-vitals → LCP for the full discussion of eagerness tradeoffs and the prerenderingchange gating you'll need for analytics.

Defer non-critical CSS:

Copy & paste — that's it

 
 /* Above-fold styles */ 

 

- 
 
-

JavaScript optimization

Defer non-essential scripts:

Copy & paste — that's it

Code splitting patterns:

Copy & paste — that's it

// Route-based splitting
const Dashboard = lazy(() => import('./Dashboard'));

// Component-based splitting
const HeavyChart = lazy(() => import('./HeavyChart'));

// Feature-based splitting
if (user.isPremium) {
 const PremiumFeatures = await import('./PremiumFeatures');
}

Tree shaking best practices:

Copy & paste — that's it

// ❌ Imports entire library
import _ from 'lodash';
_.debounce(fn, 300);

// ✅ Imports only what's needed
import debounce from 'lodash/debounce';
debounce(fn, 300);

Image optimization

Format selection

Format Use case Browser support AVIF Photos, best compression 92%+ WebP Photos, good fallback 97%+ PNG Graphics with transparency Universal SVG Icons, logos, illustrations Universal

Responsive images

Copy & paste — that's it

LCP image priority

Copy & paste — that's it

Font optimization

Loading strategy

Copy & paste — that's it

/* System font stack as fallback */
body {
 font-family: 'Custom Font', -apple-system, BlinkMacSystemFont, 
 'Segoe UI', Roboto, sans-serif;
}

/* Prevent invisible text */
@font-face {
 font-family: 'Custom Font';
 src: url('/fonts/custom.woff2') format('woff2');
 font-display: swap; /* or optional for non-critical */
 font-weight: 400;
 font-style: normal;
 unicode-range: U+0000-00FF; /* Subset to Latin */
}

Preloading critical fonts

Copy & paste — that's it

Variable fonts

Copy & paste — that's it

/* One file instead of multiple weights */
@font-face {
 font-family: 'Inter';
 src: url('/fonts/Inter-Variable.woff2') format('woff2-variations');
 font-weight: 100 900;
 font-display: swap;
}

Caching strategy

Cache-Control headers

Copy & paste — that's it

# HTML (short or no cache)
Cache-Control: no-cache, must-revalidate

# Static assets with hash (immutable)
Cache-Control: public, max-age=31536000, immutable

# Static assets without hash
Cache-Control: public, max-age=86400, stale-while-revalidate=604800

# API responses
Cache-Control: private, max-age=0, must-revalidate

Service worker caching

Copy & paste — that's it

// Cache-first for static assets
self.addEventListener('fetch', (event) => {
 if (event.request.destination === 'image' ||
 event.request.destination === 'style' ||
 event.request.destination === 'script') {
 event.respondWith(
 caches.match(event.request).then((cached) => {
 return cached || fetch(event.request).then((response) => {
 const clone = response.clone();
 caches.open('static-v1').then((cache) => cache.put(event.request, clone));
 return response;
 });
 })
 );
 }
});

Runtime performance

Avoid layout thrashing

Copy & paste — that's it

// ❌ Forces multiple reflows
elements.forEach(el => {
 const height = el.offsetHeight; // Read
 el.style.height = height + 10 + 'px'; // Write
});

// ✅ Batch reads, then batch writes
const heights = elements.map(el => el.offsetHeight); // All reads
elements.forEach((el, i) => {
 el.style.height = heights[i] + 10 + 'px'; // All writes
});

Debounce expensive operations

Copy & paste — that's it

function debounce(fn, delay) {
 let timeout;
 return (...args) => {
 clearTimeout(timeout);
 timeout = setTimeout(() => fn(...args), delay);
 };
}

// Debounce scroll/resize handlers
window.addEventListener('scroll', debounce(handleScroll, 100));

Use requestAnimationFrame

Copy & paste — that's it

// ❌ May cause jank
setInterval(animate, 16);

// ✅ Synced with display refresh
function animate() {
 // Animation logic
 requestAnimationFrame(animate);
}
requestAnimationFrame(animate);

Virtualize long lists

Copy & paste — that's it

// For lists > 100 items, render only visible items
// Use libraries like react-window, vue-virtual-scroller, or native CSS:
.virtual-list {
 content-visibility: auto;
 contain-intrinsic-size: 0 50px; /* Estimated item height */
}

Smooth navigations with View Transitions

The View Transitions API 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.

Same-document (SPA-style) — Baseline 2026:

Copy & paste — that's it

// Wrap the DOM mutation that swaps the view
function navigate(newView) {
 if (!document.startViewTransition) return swapDOM(newView);
 document.startViewTransition(() => swapDOM(newView));
}

Cross-document (MPA-style) — Chromium-stable, progressive enhancement elsewhere:

Copy & paste — that's it

/* On both source and destination pages */
@view-transition { navigation: auto; }

That'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:

Copy & paste — that's it

.product-thumb[data-id="42"], .product-hero { view-transition-name: product-42; }

Pair this with Speculation Rules (above) for instant + animated navigations.

Third-party scripts

Load strategies

Copy & paste — that's it

// ❌ Blocks main thread
 

// ✅ Async loading
 

// ✅ Delay until interaction
 
document.addEventListener('DOMContentLoaded', () => {
 const observer = new IntersectionObserver((entries) => {
 if (entries[0].isIntersecting) {
 const script = document.createElement('script');
 script.src = 'https://widget.example.com/embed.js';
 document.body.appendChild(script);
 observer.disconnect();
 }
 });
 observer.observe(document.querySelector('#widget-container'));
});

Facade pattern

Copy & paste — that's it

▶

Measurement

Key metrics

Metric Target Tool LCP < 2.5s Lighthouse, CrUX FCP < 1.8s Lighthouse Speed Index < 3.4s Lighthouse TBT < 200ms Lighthouse TTI < 3.8s Lighthouse

Testing commands

Copy & paste — that's it

# Lighthouse CLI
npx lighthouse https://example.com --output html --output-path report.html

# Web Vitals library
import {onLCP, onINP, onCLS} from 'web-vitals';
onLCP(console.log);
onINP(console.log);
onCLS(console.log);

References

For Core Web Vitals specific optimizations, see Core Web Vitals.

Copy & paste — that's it

# Lighthouse CLI
npx lighthouse https://example.com --output html --output-path report.html

# Web Vitals library
import {onLCP, onINP, onCLS} from 'web-vitals';
onLCP(console.log);
onINP(console.log);
onCLS(console.log);

Run this in your project — your agent picks the skill up automatically.