Skip to content
Michael Wegener's Learn & Projects
Blog

Astro Image Optimization Implementation Guide

Astro Image Optimization Implementation Guide

Section titled “Astro Image Optimization Implementation Guide”

In Astro 7.x, image optimization is built into the core through the astro:assets module. The deprecated @astrojs/image package has been replaced by astro:assets which provides the Image component and getImage function.

Current State: Markdown Images

Section titled “Current State: Markdown Images”

Currently, the site uses markdown images:

![Nature Landscape](/assets/images/image-generation/1-nature-landscape.png)

These are served as static PNG files without optimization.

Astro 7.x Image Optimization Approach

Section titled “Astro 7.x Image Optimization Approach”

1. Using the Image Component from astro:assets

Section titled “1. Using the Image Component from astro:assets”

In Astro 7.x, image optimization is done through the Image component:

---
import { Image, getImage } from 'astro:assets';
import natureImage from '../../../assets/images/image-generation/1-nature-landscape.png';


const optimizedImage = await getImage({
  src: natureImage,
  width: 1200,
  quality: 75,
  formats: ['webp', 'avif', 'jpeg'],
});
---


<Image
  src={optimizedImage}
  alt="Nature Landscape"
  loading="lazy"
/>

2. Starlight Markdown Image Optimization

Section titled “2. Starlight Markdown Image Optimization”

Starlight does not automatically optimize markdown images by default. To optimize images in markdown:

Option A: Use MDX with Image Component Convert markdown files to MDX and use the Image component.

Option B: Configure Starlight Image Service Starlight supports image optimization through the image service configuration.

3. Image Optimization Configuration

Section titled “3. Image Optimization Configuration”

In astro.config.mjs, you can configure image optimization:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import starlightBlog from 'starlight-blog';


export default defineConfig({
  site: 'https://michael.wegener.engineering',
  trailingSlash: 'never',
  integrations: [
    starlight({
      // ... starlight config
    }),
    starlightBlog({ /* ... */ }),
  ],
  // Image optimization configuration
  image: {
    // Astro 7.x uses built-in image optimization through astro:assets
  },
});
Section titled “Recommended Implementation”

For the current site, the recommended approach is:

  1. For blog post images: Convert markdown images to MDX and use the Image component
  2. For static assets: Continue using modern formats (AVIF, WebP) with JPEG/PNG fallbacks
  3. For team/home images: These already use modern formats with fallbacks

Implementation Steps

Section titled “Implementation Steps”

Step 1: Update Blog Post to Use MDX

Section titled “Step 1: Update Blog Post to Use MDX”

Convert site/src/content/docs/blog/2026-07-06-stable-diffusion-bilder-generieren.md to 2026-07-06-stable-diffusion-bilder-generieren.mdx and use the Image component.

Step 2: Configure Image Service

Section titled “Step 2: Configure Image Service”

Ensure Astro’s built-in image optimization is enabled for the Image component.

Step 3: Verify Optimization

Section titled “Step 3: Verify Optimization”

Check the build output for:

  • WebP and AVIF versions of images
  • srcset attributes in generated HTML
  • Optimized image files in the dist/ directory

Benefits of astro:assets

Section titled “Benefits of astro:assets”
  • Format conversion: Automatic WebP, AVIF, JPEG, PNG conversion
  • Responsive images: Auto-generated srcset attributes
  • Lazy loading: Native loading="lazy" support
  • Aspect ratio preservation: Prevents CLS (Cumulative Layout Shift)
  • Performance: Built-in optimization with no external dependencies

Further Reading

Section titled “Further Reading”