Astro Image Optimization

Astro Image Optimization

Use astro:assets and the <Image /> component to automatically optimize images at build time — enforcing alt text, generating WebP/AVIF, and preventing layout shift.

When to Use

• You are adding images to an Astro project and want automatic format conversion and size optimization
• You need responsive images with multiple source sets using <Picture />
• You are loading images from a remote URL (Cloudinary, Contentful, Unsplash) and need to configure the allowlist
• You want to use getImage() for programmatic image optimization in API endpoints or og:image generation
• You are experiencing layout shift (CLS) from images and need guaranteed width/height dimensions

Instructions

1. Import local images from src/ using a static import. Astro processes these at build time and infers dimensions automatically:

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

<!-- Astro infers width, height, and converts to WebP by default -->
<Image src={heroImage} alt="A mountain at sunrise" />

2. Use <Image /> for single-format optimized images. Required props are src and alt. Optional props control the output:

<Image
  src={heroImage}
  alt="Hero"
  width={1200}          <!-- override inferred width -->
  height={630}          <!-- override inferred height -->
  format="avif"         <!-- webp (default), avif, png, jpg -->
  quality={80}          <!-- 1-100 or 'low' | 'mid' | 'high' | 'max' -->
  loading="eager"       <!-- lazy (default) or eager -->
  decoding="async"
  class="hero-img"
/>

3. Use <Picture /> for responsive images that serve different formats and sizes based on browser support and viewport:

---
import { Picture } from 'astro:assets';
import photo from '../assets/photo.jpg';
---

<Picture
  src={photo}
  alt="Team photo"
  widths={[400, 800, 1200]}
  sizes="(max-width: 600px) 400px, (max-width: 900px) 800px, 1200px"
  formats={['avif', 'webp']}
  fallbackFormat="jpg"
/>

4. For remote images, add the hostname to image.remotePatterns in astro.config.mjs. Astro will refuse to process remote images from unlisted hostnames:

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  image: {
    remotePatterns: [
      { protocol: 'https', hostname: 'images.unsplash.com' },
      { protocol: 'https', hostname: '**.cloudinary.com' },
    ],
  },
});

5. Use remote images in <Image /> with explicit width, height, and inferSize (when dimensions cannot be known ahead of time):

<!-- Known dimensions — preferred -->
<Image src="https://images.unsplash.com/photo-abc" alt="..." width={800} height={600} />

<!-- Unknown dimensions — fetches headers to infer size (build-time cost) -->
<Image src={remoteUrl} alt="..." inferSize />

6. Use getImage() for programmatic optimization outside of templates — useful for og:image endpoints or generating image URLs for use in CSS:

// src/pages/api/og.ts
import { getImage } from 'astro:assets';
import ogBackground from '../assets/og-bg.png';

export const GET = async () => {
  const optimized = await getImage({
    src: ogBackground,
    format: 'png',
    width: 1200,
    height: 630,
  });
  // optimized.src — the final URL path
  // optimized.attributes — width, height, etc.
  return new Response(`<img src="${optimized.src}" />`);
};

7. In content collections, use the image() schema helper to process frontmatter image paths through the optimizer:

// src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      cover: image(), // validates path and enables optimization
    }),
});

---
// src/pages/blog/[slug].astro
import { Image } from 'astro:assets';
const { post } = Astro.props;
---
<Image src={post.data.cover} alt={post.data.title} width={1200} height={630} />

8. Configure the image service in astro.config.mjs. Astro uses Sharp by default in Node environments. For Cloudflare or edge deployments, switch to the no-op service and rely on the CDN:

import { defineConfig, passthroughImageService } from 'astro/config';

export default defineConfig({
  image: {
    service: passthroughImageService(), // no optimization, pass through as-is
  },
});

Details

Astro's image optimization pipeline is powered by Sharp (Node.js) or the browser's image decoding APIs (depending on deployment target). The <Image /> component enforces several best practices at compile time: alt is required (missing it is a build error), and Astro always adds explicit width and height attributes to prevent layout shift (CLS).

Format selection strategy:

• webp — best default: ~30% smaller than JPEG, universal browser support
• avif — best compression (~50% smaller than JPEG) but slower to encode at build time
• png — use only for images that need transparency
• Use <Picture /> with formats={['avif', 'webp']} and fallbackFormat="jpg" to serve the best format each browser supports

Local vs. remote image processing:

Local images (import hero from './hero.jpg') are processed at build time — the optimized file is written to dist/_astro/. Remote images are fetched during the build (SSG) or on-demand (SSR) and cached. In SSR, remote image optimization happens per-request unless you configure a CDN or caching layer.

inferSize trade-offs:

When inferSize is used on a remote image, Astro makes an HTTP HEAD request during the build to read the Content-Length or decodes the image header to determine dimensions. This adds build time proportional to the number of inferSize images. Prefer explicit width and height when the dimensions are known.

Image service configuration for edge deployments:

Sharp is a native Node.js module — it does not work on Cloudflare Workers or Vercel Edge Runtime. For edge deployments use passthroughImageService() and offload optimization to Cloudflare Image Resizing, Vercel Image Optimization, or Imgix.

Content Security Policy:

When using remote images, your CSP img-src directive must allow the remote origin. The optimized image URL will be an Astro-proxied URL in SSR mode, so only 'self' may be needed depending on configuration.

Source

https://docs.astro.build/en/guides/images

Process

1. Read the instructions and examples in this document.
2. Apply the patterns to your implementation, adapting to your specific context.
3. Verify your implementation against the details and edge cases listed above.

Harness Integration

• Type: knowledge — this skill is a reference document, not a procedural workflow.
• No tools or state — consumed as context by other skills and agents.

Success Criteria

• The patterns described in this document are applied correctly in the implementation.
• Edge cases and anti-patterns listed in this document are avoided.