Astro Image Optimization
Use astro:assets for all images. This enables automatic optimization (resizing, WebP/AVIF conversion, lazy loading).
When to Use This Skill
Use this skill when:
- Adding images to
.astroor.mdxfiles - Moving images from
/publicto optimized assets - Debugging 404s or unoptimized images in production
Rules
- Never use raw
<img>tags in.astroor.mdxfiles - Never reference images from
/public— bypasses optimization - Always import images from
src/assets/
Correct Pattern
---
import { Image } from "astro:assets";
import photo from "../assets/photo.png";
---
<Image src={photo} alt="Description" width={800} />
In MDX
---
import { Image } from "astro:assets";
import diagram from "../../assets/diagram.png";
---
<Image src={diagram} alt="Diagram" width={600} />
Linting
Run npm run lint:assets to catch violations. The linter flags:
- Raw
<img>tags in.astroand.mdxfiles (error) - Markdown images from
/publiclike(warning) - Direct
/src/paths in link/script tags (error)