Astro Images

Astro Images Skill

Authority: If any instruction conflicts with this skill, follow this skill.

Core Principle

Pattern = rendered width. Aspect ratio is independent. Browser downloads: sizes CSS px × device DPR

Container queries: approximate using viewport breakpoints. Never omit sizes.

Pattern Reference

Unknown layout → default to HALF

Layout → Pattern Mapping

Aspect ratio is independent — portrait 2:3 at 50% width = HALF pattern.

LCP Priority

Hero (1 only): loading="eager" fetchpriority="high" | Above-fold (2-3): loading="eager" | Below-fold: lazy (default)

Template (Copy-Paste)

<Picture
  src={image}
  widths={[/* from table */]}
  sizes="/* from table */"
  formats={['avif', 'webp']}
  quality={60}
  width={/* intrinsic */}
  height={/* intrinsic */}
  alt="Descriptive text"
  decoding="async"
/>

Add loading="eager" fetchpriority="high" only to ONE hero image (remove decoding on hero).

FIXED Pattern (logos, avatars)

---
import { getImage } from 'astro:assets';
const img1x = await getImage({ src: logo, width: 200, quality: 80 });
const img2x = await getImage({ src: logo, width: 400, quality: 60 });
---
<img src={img1x.src} srcset={`${img1x.src} 1x, ${img2x.src} 2x`} width="200" height="50" alt="Logo" />

Default: 1× + 2× only. 3× allowed only for icons ≥64px where fidelity matters.

Ten Rules

1. Pattern = rendered width (use table above)
2. Every <Picture> needs widths + sizes + quality={60} + formats={['avif','webp']}
3. Every image needs dimensions (explicit or inferred from Astro asset import)
4. Images in /src/assets/ — never /public/
5. Only ONE fetchpriority="high" per page — never in loops
6. sizes must match CSS layout — no defensive 100vw
7. Use exact arrays from table — no custom/computed/dynamic widths
8. Preserve aspect ratio — no cropping without art direction
9. Alt text: descriptive for content, alt="" only for decorative
10. Unknown layout → HALF pattern

Raw <img> allowed only for: FIXED pattern, SVGs, external URLs.

Pre-Output Checklist

• Pattern matches width? | Width array exact? | sizes matches CSS? | width/height present?
• quality={60}? | fetchpriority="high" max once, not in loop? | Image from /src/assets/?

If any NO → fix before outputting.

Forbidden

• <Picture> for SVGs (use <img>) | Animated GIF/APNG (use <video>) | CSS backgrounds for LCP
• Images in /public/ | Upscaling sources | Dynamic/computed width arrays

Undersized Source Fallback

If source < pattern minimum: cap widths array at source width, keep sizes unchanged, flag for replacement. Example: 1200px source for HALF → widths={[320,640,960,1200]} (removed 1280,1600) Exception: FULL/LCP images — undersized is ERROR, must provide larger asset.

Source Minimums

FULL: 2560px | TWO_THIRDS: 2048px | LARGE: 1920px | HALF: 1600px | SMALL/THIRD: 1280px | QUARTER: 960px | FIFTH: 768px | SIXTH: 640px

Schema Images (Google)

3 versions in /src/assets/schema/: 1:1 (1200×1200), 4:3 (1200×900), 16:9 (1200×675) Reference in schema AND og:image.

Cloudflare Adapter Configuration

Critical: Cloudflare Workers/Pages does NOT support Sharp at runtime. Without proper config, no images will be optimized.

Wrong (no optimization):

export default defineConfig({
  output: 'server',
  adapter: cloudflare()
});
// ⚠️ [WARN] Cloudflare does not support sharp at runtime
// Result: Only original JPGs in dist, no AVIF/WebP

Correct (build-time optimization):

export default defineConfig({
  output: 'static',
  adapter: cloudflare({
    imageService: 'compile'
  }),
  image: {
    service: {
      entrypoint: 'astro/assets/services/sharp'
    }
  }
});

Key settings:

• output: 'static' → Build-time generation (SSR pages use prerender: false)
• imageService: 'compile' → Optimize at build, not runtime
• image.service.entrypoint → Use Sharp for build-time processing

Verify after build:

ls dist/_astro/*.avif | head -5  # Should show AVIF files
ls dist/_astro/*.webp | head -5  # Should show WebP files

Validation

find public -type f \( -name "*.jpg" -o -name "*.png" -o -name "*.webp" \) 2>/dev/null
grep -r "<Picture" src --include="*.astro" | grep -v "widths="
grep -r "fetchpriority" src --include="*.astro" | grep -E "\.(map|forEach)\("