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 .astro or .mdx files
• Moving images from /public to optimized assets
• Debugging 404s or unoptimized images in production

Rules

• Never use raw <img> tags in .astro or .mdx files
• 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 .astro and .mdx files (error)
• Markdown images from /public like ![](/image.png) (warning)
• Direct /src/ paths in link/script tags (error)