astro-assets

name	astro-assets
description	Image and asset optimization in Astro 7 — <Image />, <Picture />, getImage(), remote images, @astrojs/sharp, Fonts API, OG image generation with Satori, Cloudinary/Imgix. Use for any image optimization or asset handling task.

Astro Assets

Targets: Astro 7.

Production-ready image optimization and asset management with astro:assets in Astro 7.

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 parallel agents (Codex spawn_agent):

1. explore-codebase - Analyze existing image usage and asset patterns
2. research-expert - Verify astro:assets API via Context7/Exa
3. Context7 (official docs) - Check Astro 6 Fonts API and image component docs

After implementation, run sniper for validation.

---

Overview

When to Use

• Displaying optimized images with automatic WebP/AVIF conversion
• Building responsive images with multiple breakpoints
• Loading remote images from external CDNs
• Configuring custom fonts without layout shift
• Generating OG images dynamically with Satori
• Integrating Cloudinary or Imgix as image CDN

Key Modules

Module	Exports
astro:assets	<Image />, <Picture />, getImage()
@astrojs/sharp	Default image processing service
Fonts API (stable, Astro 6.0+)	Built-in fonts config

---

Core Concepts

Image Component

<Image /> automatically optimizes local and remote images. Always provide alt. Use priority for above-the-fold images. Defaults to WebP output.

Picture Component

<Picture /> generates <source> elements for multiple formats. Use formats={['avif', 'webp']} for best compression with fallback.

getImage()

For server-side image generation (API routes, CSS background images). Returns { src, attributes } object.

Fonts API (stable, Astro 6.0+)

Built-in font optimization via the top-level fonts config in astro.config.mjs (stable since Astro 6.0 — no experimental flag). Zero layout shift, automatic preloading, supports Google Fonts and local fonts.

---

Reference Guide

Concepts

Topic	Reference	When to Consult
Image Component	image-component.md	Local/remote image display
Responsive Images	picture-responsive.md	Multi-format, srcset, sizes
Remote Images	remote-images.md	External URLs, inferSize
Fonts API	fonts-api.md	Zero-CLS font loading
OG with Satori	og-satori.md	Dynamic OG image generation
CDN Integration	cdn-integration.md	Cloudinary, Imgix setup

Templates

Template	When to Use
image-setup.md	Full image optimization setup
og-image-route.md	Dynamic OG image API route

---

Best Practices

1. Always provide alt - Required for accessibility and SEO
2. Use priority for LCP - Above-the-fold images load eagerly
3. inferSize for remote - Avoids layout shift without known dimensions
4. Fonts API over @font-face - Built-in optimization, no manual preload
5. Satori at build time - Run OG generation during SSG, not SSR