image/4/io
Framework Guides· Framework Guide

Astro image optimization guide

How to use Astro assets, responsive layouts, and remote image rules without bloating static builds.

Astro gives you strong asset tooling, but static sites still suffer when image generation is unconstrained. The right page explains what belongs in build-time transforms and what should stay on a CDN.

Best for

Content-heavy static or hybrid Astro sites

Default goal

Build-time control with predictable responsive output

Watch closely

Remote image handling and build cost

Recommended setup

Use Astro assets for local editorial media and document when remote or CMS images should bypass local processing. Static sites often become slow to build because every remote image starts doing local work.

  • Use imported local assets for images you publish and control.
  • Keep remote-domain rules specific and explicit.
  • Move highly dynamic or third-party media to a CDN-backed workflow instead of forcing everything through the build.

Responsive Astro image

---
import { Image } from 'astro:assets'
import hero from '../assets/hero.jpg'
---

<Image
  src={hero}
  alt="Editorial hero"
  widths={[480, 768, 1200]}
  sizes="(min-width: 1024px) 1200px, 100vw"
  formats={['avif', 'webp']}
/>

What to measure

  • Build time and asset-generation volume after adding responsive widths.
  • Byte savings between source assets and delivered formats.
  • How many templates still fall back to raw `<img>` tags without sizing rules.

Where Astro-specific value comes from

Searchers looking for Astro image optimization usually want a boundary: what Astro should optimize locally, what the CDN should handle, and how to keep builds sane.

Checklist

  • Use imported assets for local images.
  • Set width ladders per layout, not globally by habit.
  • Keep remote image domains restricted.
  • Avoid expensive build-time transforms for volatile content.

Common mistakes

  • Generating too many width variants for every image.
  • Running remote media through the build when a CDN would be more stable.
  • Ignoring aspect ratios and relying on CSS alone to fix layout.

Quick answers

When should Astro handle image optimization locally?

When the media is part of your repo or a stable content workflow and the output is predictable enough to justify build-time processing.

What usually makes Astro image builds slow?

Too many generated widths, too many formats, or trying to process large remote image inventories during static builds.