Web Performance

Web Performance: Decide It Up Front

Performance is an architecture decision made at the start, not a cleanup pass at the end. The first question for anything user-facing is: what does the user need to see and interact with first, and what can wait. Build to that split. Loading everything eagerly and optimizing later is the expensive path, and it's the one Claude defaults to.

Split first paint from later, and load each accordingly

Sort every resource into two buckets and treat them differently:

• Critical, needed for first paint (above the fold, the main content and its styles): put it in the initial HTML, inline the critical CSS (see css-structure), preload the largest image and the one critical font.
• Later (below the fold, interactions, secondary features, third-party): defer it. Lazy-load below-fold images and iframes natively with loading="lazy", no JavaScript library or IntersectionObserver needed, the browser handles it, and on an iframe it defers heavy third-party embeds like maps and video players too. Then defer or async non-critical scripts, dynamic-import offscreen components and routes, and load analytics and third-party tags late and async.

Don't let CSS or JS block first paint

CSS is render-blocking: a single large stylesheet delays the first paint until it's downloaded and parsed. Inline the above-the-fold slice and load the rest without blocking (<link rel="preload" as="style" onload="this.rel='stylesheet'">, or a media swap). A <script> in <head> without defer blocks HTML parsing; use defer (runs after parse, in order) or async (independent scripts), or put scripts at the end of <body>. Keep the number of render-blocking requests small.

The LCP element gets priority and is never lazy-loaded

The Largest Contentful Paint is usually the hero image or headline above the fold, and it's the metric users feel as "has it loaded yet." Preload it, mark it fetchpriority="high", and serve it correctly sized and compressed. Do NOT put loading="lazy" on it, that's a common mistake that delays the very thing LCP measures. Lazy-loading is for everything below the fold, not the first thing on screen.

Reserve space so nothing shifts (CLS)

Layout shift is almost always a box whose size wasn't reserved before its contents arrived: the element loads late, shoves everything below it down, and the browser reflows and repaints.

Always give images a width and height whenever you can. Set the intrinsic pixel dimensions as HTML attributes so the browser reserves the correct box, and works out the aspect ratio, before a single image byte arrives. Pair it with CSS so it still scales responsively:

<img src="hero.avif" width="1600" height="900" alt="..." />

img { max-width: 100%; height: auto; }   /* scales to the column, keeps the reserved ratio */

Without the attributes the image takes up no height until it loads, then snaps to full size and pushes the page down. For backgrounds or anything where you can't set attributes, reserve the box with aspect-ratio. Do the same for video, ads, and embeds, and don't inject content above content that's already visible. For web fonts, use a font-display strategy with a size-adjusted fallback so text doesn't reflow when the real font swaps in. CLS is mostly "you didn't reserve the space."

Images and fonts are usually the biggest wins

These two categories dwarf most JavaScript micro-tuning:

• Images, convert to WebP (or AVIF). WebP is typically 25 to 35% smaller than JPEG and much smaller than PNG at the same quality, and it supports transparency, so it replaces both. AVIF is smaller still where you can use it. This is often the single biggest size win on a page. Serve them through <picture> so the browser takes the best format it supports and older ones still get a fallback, and convert at build time (sharp in Node, or squoosh / cwebp):

<picture>
  <source srcset="hero.avif" type="image/avif" />
  <source srcset="hero.webp" type="image/webp" />
  <img src="hero.jpg" width="1600" height="900" alt="..." />
</picture>

Serve multiple resolutions natively too: a srcset of width variants plus sizes lets the browser download only the size that fits the viewport and pixel density, with no JavaScript. A phone grabs the small file, a retina desktop the large one, off one tag:

<img src="img-800.webp" width="1600" height="900" alt="..."
     srcset="img-400.webp 400w, img-800.webp 800w, img-1600.webp 1600w"
     sizes="(max-width: 600px) 100vw, 800px" />

The same srcset/sizes sit on each <picture> source to combine format and size, and <picture> with media also does art direction (a different crop per breakpoint). Two things not to convert: vector art (logos, icons) stays SVG, don't rasterize it, and animated GIFs should become video (MP4/WebM), a GIF is enormous. And actually compress, a full-resolution PNG hero is the most common single performance bug.

• Fonts: self-host or preconnect, subset to the characters used, preload the one critical face, and don't pull four weights when you use two.