Image Optimisation
debt(d5/e5/b3/t5)
Closest to 'specialist tool catches it' (d5). The detection_hints list Lighthouse, Squoosh, and ImageOptim — all specialist/audit tools rather than compiler or default linter checks. Lighthouse flags unoptimised images and missing width/height attributes, but these issues won't surface in normal development flow; a deliberate audit run is required.
Closest to 'touches multiple files / significant refactor in one component' (e5). The quick_fix mentions adopting PHP Intervention Image or Spatie Media Library to auto-generate AVIF/WebP on upload, wrapping images in <picture> elements, adding width/height attributes, and adding lazy loading. This touches upload pipelines, template/view files, and potentially CDN/storage configuration — spanning multiple files and components rather than a single-line swap.
Closest to 'localised tax' (b3). The applies_to scope is web-only contexts, and the changes (image pipeline, markup patterns) are largely confined to media handling and frontend templates. The rest of the codebase is largely unaffected, though every image-rendering template must be updated, making it a moderate localised tax rather than a system-wide one.
Closest to 'notable trap' (t5). The misconception field documents a well-known but counterintuitive gotcha: developers assume JPEG quality 100 is necessary for product images, when quality 80-85 is visually indistinguishable and 3-5x smaller. This is a documented gotcha that most developers eventually learn, and common_mistakes reinforce additional non-obvious traps (missing width/height causing CLS, missing fallbacks for AVIF/WebP).
Also Known As
TL;DR
Explanation
Image optimisation layers: format (AVIF > WebP > JPEG/PNG), dimensions (never serve larger than displayed), compression level (quality 75-85 for JPEG, lossless for logos), lazy loading (loading=lazy), responsive images (srcset), and CDN delivery. AVIF: 50% smaller than JPEG with equal quality, supported by modern browsers. WebP: 25-35% smaller than JPEG, broader support. Use the picture element for format selection with JPEG/PNG fallback. Automate with Cloudinary, imgproxy, or build-time tools (sharp, Squoosh).
Common Misconception
Why It Matters
Common Mistakes
- Not providing AVIF/WebP with JPEG fallback — use the picture element.
- Serving hero images at 4K when displayed at 800px — always resize to max displayed dimensions.
- No lazy loading on below-fold images — load=lazy saves bandwidth on every page load.
- Not setting width and height attributes — causes layout shift (CLS) while images load.
Code Examples
<!-- Unoptimised — 2.4MB JPEG displayed at 400px:
<img src="hero.jpg" style="width:400px">
<!-- JPEG quality 95, 2400x1600px, no lazy loading, no srcset --><!-- Optimised with modern formats + responsive:
<picture>
<source srcset="hero-400w.avif 400w, hero-800w.avif 800w"
type="image/avif">
<source srcset="hero-400w.webp 400w, hero-800w.webp 800w"
type="image/webp">
<img src="hero-800w.jpg"
srcset="hero-400w.jpg 400w, hero-800w.jpg 800w"
sizes="(max-width:600px) 400px, 800px"
width="800" height="400"
loading="lazy"
alt="Hero image">
</picture>
<!-- Result: 120KB vs 2.4MB — 20x smaller -->