---
name: web-performance
description: 'Use this skill whenever the user is improving Core Web Vitals or page load performance, or mentions slow pages, PageSpeed Insights / Lighthouse failures, LCP/CLS/INP scores, bundle size, image/font optimization, or third-party script impact. Covers Core Web Vitals, image and font optimization, JavaScript bundle size, CSS build size, CDN caching, third-party JavaScript impact, and measurement tools. Skip for backend latency tuning, database query optimization, or CI build speed.'
---
# Web Performance Guide
> Applies to: Any website or web app | Updated: March 2026
A practical reference for measuring and improving web performance - covering Core Web Vitals, image and font optimization, JavaScript bundle size, CSS build size, CDN caching, third-party JavaScript impact, and validation tools.
---
## Section 0: Before You Start
Answer these questions before making any performance changes. Each has a default - use it if the user hasn't said otherwise.
**Q: Which pages are the priority targets?**
(landing page, dashboard, auth-gated app pages, all pages)
Default: public-facing pages first - these are indexed by search engines and directly affect user experience. Auth-gated pages matter less for Core Web Vitals field data because CrUX only collects data from logged-in users on those routes.
**Q: What is the current performance baseline?**
Default: unknown - run PageSpeed Insights on the target URL before making any changes, so you have a before/after comparison. Note the LCP element type (image or text), TTFB, and the specific audits flagged as failing.
**Q: Are you optimizing for lab scores (Lighthouse) or field data (real users)?**
Default: both - but prioritize fixing field data issues flagged in Google Search Console > Core Web Vitals first. Lab scores are easier to game; field data reflects real users on real devices and networks.
**Q: What framework or rendering model is the site using?**
(plain HTML, SPA/Vite, Next.js App Router, Astro, Nuxt, WordPress)
Default: detect from config files (`next.config.*`, `vite.config.*`, `astro.config.*`) if visible; otherwise assume plain HTML. Framework-specific advice is in clearly labeled subsections throughout this guide.
**Q: What image formats are currently in use?**
Default: JPEG/PNG - check the `public/` or `assets/` directory and any image references in source before assuming.
**Q: How are web fonts loaded?**
(Google Fonts via ``, `@import` in CSS, self-hosted, framework font utility)
Default: check the HTML `` and any global CSS files before assuming.
**Q: Is a CDN or hosting platform configured with custom cache headers?**
Default: no - most platforms (AWS Amplify, plain S3, some shared hosts) do not set long-lived cache on static assets by default. Check the hosting config before assuming.
**Q: Is a `browserslist` target configured?**
Default: no - without it, many transpilers and bundlers use a conservative target and ship legacy polyfills for features that modern browsers have supported for years.
> **AI assistant:** Read the user's answers (or use the defaults above) before generating any code. Run PageSpeed Insights first if no baseline exists. Identify the LCP element type before optimizing images - if the LCP element is a `
` or `
`, TTFB and render-blocking CSS reduction matter more than image optimization. Skip framework-specific subsections that don't match the user's stack.
---
## Contents
1. [Core Web Vitals Overview](#core-web-vitals-overview)
2. [LCP: Largest Contentful Paint](#lcp-largest-contentful-paint)
3. [CLS: Cumulative Layout Shift](#cls-cumulative-layout-shift)
4. [INP: Interaction to Next Paint](#inp-interaction-to-next-paint)
5. [Image Optimization](#image-optimization)
6. [Font Loading](#font-loading)
7. [JavaScript Bundle Size](#javascript-bundle-size)
8. [Legacy JavaScript and Browser Targets](#legacy-javascript-and-browser-targets)
9. [Third-Party JavaScript](#third-party-javascript)
10. [CSS Build Size](#css-build-size)
11. [CDN and Caching](#cdn-and-caching)
12. [Measurement and Validation](#measurement-and-validation)
---
## Core Web Vitals Overview
Applies when: any public-facing page.
Core Web Vitals are Google's user-experience metrics, measured in the field via the Chrome User Experience Report (CrUX). They are ranking signals. The three metrics as of 2026:
| Metric | Measures | Good | Needs improvement | Poor |
|---|---|---|---|---|
| **LCP** | Loading speed of the largest visible element | < 2.5 s | 2.5 - 4 s | > 4 s |
| **CLS** | Visual instability from layout shifts | < 0.1 | 0.1 - 0.25 | > 0.25 |
| **INP** | Responsiveness of all interactions | < 200 ms | 200 - 500 ms | > 500 ms |
INP replaced FID (First Input Delay) in March 2024. FID only measured the first interaction; INP measures every interaction throughout the visit. A page that passes INP must remain responsive throughout the entire session, not just at initial load.
Field data appears in Google Search Console after a URL accumulates enough traffic. Until then, use PageSpeed Insights lab data (Lighthouse) as a proxy.
---
## LCP: Largest Contentful Paint
Applies when: any page with a hero section, large image, or above-the-fold text block.
**Identify the LCP element before optimizing.** The LCP element is not always an image. On text-heavy marketing pages it is often a `
` or `
`. When the LCP element is text, the highest-impact fixes are TTFB reduction and eliminating render-blocking CSS - not image optimization.
> **Real-world example:** On a marketing home page, PageSpeed Insights identified the LCP element as a `
` paragraph tag, not an image. TTFB was 610 ms and element render delay was 230 ms. The correct optimization targets were redirect chains (adding 607 ms before the first byte) and render-blocking CSS chunks - not image format conversion.
### Eliminate render-blocking resources
Render-blocking resources delay the LCP element from painting. CSS files loaded as `` in `
` block rendering until they download and parse.
> **Real-world example:** PageSpeed Insights flagged two render-blocking CSS chunks on a marketing page - 13.6 KiB and 1.2 KiB - adding approximately 400 ms to LCP. These were a global stylesheet and a component stylesheet generated by the framework's default CSS chunking behavior.
**Universal approach:** Inline critical CSS (the styles needed to render above-the-fold content) directly into the HTML ``. Load the rest of the stylesheet asynchronously:
```html
```
#### Next.js App Router
Next.js 15 generates separate CSS chunks for `globals.css` and component styles. Two experimental options reduce or eliminate the render-blocking effect:
**Option 1: Enable CSS inlining.**
The `experimental.inlineCss` flag embeds CSS directly into the HTML `` instead of linking external files, eliminating separate CSS download requests:
```ts
// next.config.ts
const nextConfig: NextConfig = {
experimental: {
inlineCss: true,
},
};
```
This is experimental as of Next.js 15. Test in staging before deploying. Real-world reports show Lighthouse scores improving from 94 to 100 after enabling this flag.
**Option 2: Use `cssChunking: 'strict'`.**
Loads CSS in exact import order, which can reduce out-of-order loading penalties:
```ts
// next.config.ts
const nextConfig: NextConfig = {
experimental: {
cssChunking: 'strict',
},
};
```
`inlineCss` is the stronger fix for LCP. Neither fully resolves render-blocking CSS in Next.js 15; this is a known framework-level issue tracked in the Next.js repository.
### Reduce server response time (TTFB)
A slow Time to First Byte delays everything downstream.
**Universal strategies:**
- Serve static pages from a CDN edge node close to the user
- Avoid redirect chains before the HTML response (see [CDN and Caching](#cdn-and-caching))
- Cache rendered pages where content does not change per-request
#### Next.js App Router
Server Components that await slow database queries block initial HTML delivery:
- Move non-critical data fetching into child Server Components so the page shell renders immediately
- Use `loading.tsx` (React Suspense boundaries) to stream the shell while data loads
- Add `unstable_cache` or `cache()` to repeated queries that don't need to be fresh on every request
```tsx
import { Suspense } from 'react';
// Shell renders immediately; DataList streams in when data is ready
export default function Page() {
return (
Page Title
}>
);
}
```
### Preload the LCP image
When the LCP element is an image, add an explicit preload hint so the browser fetches it as early as possible:
```html
```
Only preload the LCP element. Adding preload hints to multiple images creates competing requests and can worsen LCP.
#### Next.js App Router
For images rendered via `next/image`, use the `priority` prop - it generates the preload link automatically and disables lazy loading:
```tsx
import Image from 'next/image';
```
---
## CLS: Cumulative Layout Shift
Applies when: any page with images, dynamically loaded content, or web fonts.
CLS measures how much the page layout shifts after initial render. Shifts are jarring and cause accidental taps on mobile.
### Always set image dimensions
Every `` must have explicit `width` and `height` attributes. Without these, the browser does not reserve space for the image, causing a layout shift when it loads:
```html
```
For images that fill their container (unknown intrinsic dimensions), use CSS `aspect-ratio` on the container:
```css
.image-container {
width: 100%;
aspect-ratio: 16 / 9;
overflow: hidden;
}
```
### Avoid injecting content above existing content
Elements that load after the initial render and push content down cause high CLS. Common causes:
- Auth user interface components (avatar, username) rendering after hydration - reserve space with a fixed-size skeleton
- Toast notifications that push content down instead of overlaying it - use an overlay-based notification library positioned at the screen edge
- Ad or analytics scripts that inject banners - avoid this; if unavoidable, reserve the space before the script loads
### Stabilize font loading
Web fonts that load after the initial render cause text to reflow (FOUT: Flash of Unstyled Text). Use `font-display: optional` for body fonts to avoid shifts, or `font-display: swap` if the FOUT is visually acceptable.
---
## INP: Interaction to Next Paint
Applies when: any page with user interactions - especially dashboards, data-entry forms, and interactive app flows.
INP measures how quickly the browser responds to every tap, click, or key press. A 200 ms response budget is tight on slow devices.
### DOM size and INP
Larger DOM trees slow down style recalculation, layout, and paint operations that happen during every interaction. Google recommends fewer than 1,500 DOM nodes, a maximum depth of 32, and no more than 60 children per parent node.
> **Real-world example:** PageSpeed Insights measured 366 DOM nodes and a maximum depth of 13 on a marketing home page. At this scale the impact is minor, but it establishes a baseline to watch as the page grows. For pages with deeply nested component trees or large data tables, DOM size becomes a meaningful INP contributor.
### Long main-thread tasks
Any synchronous operation over 50 ms on the main thread will cause high INP for interactions that happen during or just after it. Long tasks appear in PageSpeed Insights under "Avoid long main-thread tasks" and in the Chrome DevTools Performance tab as red-marked task bars.
> **Real-world example:** PageSpeed Insights identified three long main-thread tasks on a marketing page: 80 ms and 64 ms from own JavaScript, and 60 ms from a third-party auth initialization script. The own-JS tasks should be profiled in Chrome DevTools Performance tab to identify the specific call stacks. The third-party task is addressed in [Third-Party JavaScript](#third-party-javascript).
### Debounce expensive input handlers
Text inputs that trigger live validation, filtering, or search on every keystroke create large INP values. Use `useDeferredValue` (React) or `debounce` to defer expensive work:
```tsx
import { useDeferredValue, useState } from 'react';
function SearchFilter({ items }: { items: Item[] }) {
const [query, setQuery] = useState('');
const deferredQuery = useDeferredValue(query);
// filteredItems uses the deferred value - won't block the input response
const filteredItems = items.filter((item) =>
item.name.toLowerCase().includes(deferredQuery.toLowerCase())
);
return (
<>
setQuery(e.target.value)} />
);
}
```
For non-React setups, use a debounce helper:
```js
function debounce(fn, delay) {
let timer;
return (...args) => {
clearTimeout(timer);
timer = setTimeout(() => fn(...args), delay);
};
}
input.addEventListener('input', debounce(handleSearch, 150));
```
### Break up long synchronous tasks
Use `scheduler.yield()` (or `setTimeout(fn, 0)` as a fallback) to yield control back to the browser between chunks of work:
```js
async function processInChunks(items) {
const CHUNK_SIZE = 100;
const results = [];
for (let i = 0; i < items.length; i += CHUNK_SIZE) {
const chunk = items.slice(i, i + CHUNK_SIZE);
results.push(...chunk.map(processItem));
// Yield to the browser between chunks
if ('scheduler' in window && 'yield' in window.scheduler) {
await window.scheduler.yield();
} else {
await new Promise((resolve) => setTimeout(resolve, 0));
}
}
return results;
}
```
### Optimistic UI for slow server operations
Server requests that take more than 200 ms to return will cause the UI to appear frozen if button state is tied to the request's completion. Apply optimistic updates immediately and reconcile with the server response afterward:
```tsx
'use client';
import { useOptimistic, useTransition } from 'react';
function ToggleStatus({ item }: { item: Item }) {
const [optimisticActive, setOptimisticActive] = useOptimistic(item.isActive);
const [isPending, startTransition] = useTransition();
function handleToggle() {
startTransition(async () => {
setOptimisticActive(!optimisticActive);
await toggleItemAction(item.id);
});
}
return (
);
}
```
---
## Image Optimization
Applies when: any page with images.
### Use an image component or build-time processing
Framework image components and build-time tools handle format conversion, responsive sizing, and lazy loading automatically. Use them instead of plain `` tags for content images.
| Approach | Tools |
|---|---|
| Next.js | `next/image` - converts to WebP/AVIF, lazy loads, generates `srcset` |
| Vite / SPA | `vite-imagetools`, `@unpic/react`, or manual pre-conversion |
| Astro | `` component built into Astro core |
| Plain HTML | Pre-convert images to WebP/AVIF using `sharp`, `squoosh`, or `sips` |
#### Next.js App Router
```tsx
import Image from 'next/image';
```
The `sizes` attribute is the most commonly missed configuration. Without it, the image is generated at full width for every viewport, wasting bandwidth on mobile.
For images loaded from external sources (S3, a CDN, a third-party service), configure allowed domains:
```ts
// next.config.ts
const nextConfig: NextConfig = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'your-bucket.s3.amazonaws.com',
pathname: '/uploads/**',
},
],
},
};
```
### Source format recommendations
| Source material | Recommended format | Notes |
|---|---|---|
| Photographs | WebP or AVIF | AVIF achieves 90-95% size reduction over JPEG at equivalent quality |
| Logos, icons | SVG | Inline SVG or `` - bypass image processing for SVG |
| Screenshots | WebP | PNG source is fine; let the image tool convert |
| Animated content | WebP or AVIF (animated) | Avoid GIF; file sizes are 5-10x larger than equivalent WebP |
Keep the highest-quality source and let the image tool handle conversion. Pre-converting lossy-to-lossy degrades quality unnecessarily.
### Lazy loading and above-the-fold images
Lazy load all images below the fold. For images visible in the initial viewport without scrolling, disable lazy loading and add a preload hint:
```html
```
---
## Font Loading
Applies when: any page using custom web fonts.
### Prefer self-hosted fonts over Google Fonts CDN
Serving fonts from your own domain eliminates the external DNS lookup and connection to a third-party CDN. Self-hosted fonts load from the same origin as your HTML, which is almost always faster.
#### Next.js App Router
`next/font` self-hosts fonts automatically, eliminating the external network request to Google Fonts. It inlines the `@font-face` CSS and generates a preload hint:
```tsx
// src/app/layout.tsx
import { Inter } from 'next/font/google';
const inter = Inter({
subsets: ['latin'],
display: 'swap',
variable: '--font-inter',
});
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
#### Vite / SPA
Use `fontsource` packages to bundle fonts with your build output:
```bash
npm install @fontsource/inter
```
```js
// main.js / main.ts
import '@fontsource/inter/400.css';
import '@fontsource/inter/700.css';
```
#### Plain HTML
Self-host font files in your static directory and reference them with `@font-face` in CSS. Add a `` hint in `` for the most critical font weight:
```html
```
### font-display strategy
| Value | Behavior | Use when |
|---|---|---|
| `swap` | Invisible text until font loads, then swap | Headlines; FOUT is acceptable |
| `optional` | Browser uses fallback if font doesn't load in ~100 ms | Body text; eliminates CLS |
| `block` | Invisible text for up to 3 seconds | Never, for performance |
For body text that spans multiple lines, `optional` eliminates CLS entirely but means the custom font may not render on slow connections. `swap` is the better choice for branding-critical fonts.
### Avoid @import in CSS
Never load fonts via `@import` inside a `.css` file or a `
` - bypass image processing for SVG |
| Screenshots | WebP | PNG source is fine; let the image tool convert |
| Animated content | WebP or AVIF (animated) | Avoid GIF; file sizes are 5-10x larger than equivalent WebP |
Keep the highest-quality source and let the image tool handle conversion. Pre-converting lossy-to-lossy degrades quality unnecessarily.
### Lazy loading and above-the-fold images
Lazy load all images below the fold. For images visible in the initial viewport without scrolling, disable lazy loading and add a preload hint:
```html
```
---
## Font Loading
Applies when: any page using custom web fonts.
### Prefer self-hosted fonts over Google Fonts CDN
Serving fonts from your own domain eliminates the external DNS lookup and connection to a third-party CDN. Self-hosted fonts load from the same origin as your HTML, which is almost always faster.
#### Next.js App Router
`next/font` self-hosts fonts automatically, eliminating the external network request to Google Fonts. It inlines the `@font-face` CSS and generates a preload hint:
```tsx
// src/app/layout.tsx
import { Inter } from 'next/font/google';
const inter = Inter({
subsets: ['latin'],
display: 'swap',
variable: '--font-inter',
});
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
#### Vite / SPA
Use `fontsource` packages to bundle fonts with your build output:
```bash
npm install @fontsource/inter
```
```js
// main.js / main.ts
import '@fontsource/inter/400.css';
import '@fontsource/inter/700.css';
```
#### Plain HTML
Self-host font files in your static directory and reference them with `@font-face` in CSS. Add a `` hint in `` for the most critical font weight:
```html
```
### font-display strategy
| Value | Behavior | Use when |
|---|---|---|
| `swap` | Invisible text until font loads, then swap | Headlines; FOUT is acceptable |
| `optional` | Browser uses fallback if font doesn't load in ~100 ms | Body text; eliminates CLS |
| `block` | Invisible text for up to 3 seconds | Never, for performance |
For body text that spans multiple lines, `optional` eliminates CLS entirely but means the custom font may not render on slow connections. `swap` is the better choice for branding-critical fonts.
### Avoid @import in CSS
Never load fonts via `@import` inside a `.css` file or a `