Astro Image Optimization Implementation Guide

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

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

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

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

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
  },
});

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

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

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

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

• 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

• Astro Assets Documentation
• Starlight Image Support
• Web Performance: Image Optimization