Next Image Optimization

Next.js Image Optimization

When to use

• Writing a new page/component that renders images
• Reviewing a PR that touches src/app/** or any component with <img> / <Image> tags
• Auditing a page with bad LCP (correlates with hero image issues)
• Before shipping any hero section change

Hard rules

1. NEVER use raw <img> tags in JSX/TSX. Always <Image> from next/image. The only exception: external SVGs that Next.js can't optimize (e.g. Twitter widgets) — and even those should be wrapped in a component.

2. Hero / above-fold images MUST have priority:

   <Image
     src="/images/serengeti-hero.webp"
     alt="Serengeti plains at sunrise"
     priority
     width={1920}
     height={1080}
     sizes="(max-width: 768px) 100vw, (max-width: 1200px) 80vw, 1200px"
     className="object-cover"
   />
   

3. alt attribute ALWAYS — empty string alt="" is acceptable ONLY for decorative images. Screen readers need this.

4. Explicit width + height on all <Image> — prevents CLS. For dynamic images, use fill + aspect-ratio container.

5. Format precedence — source should be in this order:

   • .avif (best, ~30% smaller than webp)
   • .webp (widely supported)
   • .jpg / .png (fallback only) NEVER ship images as .jpg or .png unless you're sure AVIF/WebP conversion isn't available in the pipeline.

6. sizes attribute — not optional. Without it, Next serves the largest size on every device. Minimal example for responsive images:

   sizes="(max-width: 768px) 100vw, 50vw"
   

Procedure (for review)

1. Find all images in the PR diff:

   git diff main...HEAD --name-only | xargs grep -lE '<img|<Image' 2>/dev/null | head
   

2. For each file, check:

   • No <img> tags → use <Image> or MDXImage wrapper
   • Hero image has priority prop
   • All have alt
   • All have width+height OR fill with sized container
   • sizes attribute present on responsive layouts
   • Source format is AVIF or WebP

3. Check public/images/ — ensure file formats are good:

   find public/images -name "*.jpg" -o -name "*.png" | head -20
   

   Any JPG/PNG over 200 KB is a conversion candidate. Convert with sharp or cwebp:

   npx @squoosh/cli --webp '{"quality":80}' public/images/*.jpg
   

4. LCP protection — run this after build to see which image is the LCP:

   npx lighthouse http://localhost:3000/ --only-audits=largest-contentful-paint-element --output=json --quiet --chrome-flags="--headless --no-sandbox" | jq '.audits["largest-contentful-paint-element"].displayValue'
   

   Verify the element has priority and is WebP/AVIF.

Site-specific image rules

Common issues + fixes

Pitfalls

• priority on multiple images per page = defeats the purpose. Max 1-2 hero images.
• placeholder="blur" with external URLs requires explicit blurDataURL. Don't try on dynamic remote images without it.
• next/image with external domains requires allowlist in next.config.js images.remotePatterns. If a remote image breaks after deploy, check this.
• AVIF has browser support gaps on older iOS — Next auto-fallbacks to WebP, so you're fine.

Related skills

• core-web-vitals-audit — LCP/CLS/INP diagnosis
• accessibility-audit — alt text auditing
• next-build-gate — catches image config errors at build time

Budget

$0.05–0.15 per PR review. Conversion scripts are free.

Source: donkassim/paperclip — distributed by TomeVault.