Skip to main content

​
Overview

Vercel Image Optimization automatically optimizes images on-demand, serving them in modern formats like WebP with the right size for each device. This improves performance without manual image processing.
Images are optimized at the edge and cached globally, providing fast load times for users worldwide.

​
Configuration

Enable image optimization in your Astro config:
astro.config.mjs
import vercel from '@astrojs/vercel'
import { defineConfig } from 'astro/config'

export default defineConfig({
  adapter: vercel({
    imageService: true,
    imagesConfig: {
      sizes: [320, 640, 1280],
      domains: [],
      remotePatterns: [
        {
          protocol: 'https',
        },
      ],
    },
  }),
})

​
Configuration Options

// Enable Vercel Image Optimization
imageService: true

​
Using the Image Component

Import and use the Astro Image component:
src/pages/image.astro
---
import { Image as AstroImage } from 'astro:assets'
import imageDark from '@/assets/images/context-menu-dark.jpg'
import imageLight from '@/assets/images/context-menu-light.jpg'
import Layout from '@/layouts/Layout.astro'
---

<Layout seo={{ title: 'Image', description: 'Astro Asset using Vercel Image Optimization' }}>
  <section>
    <hgroup>
      <h2>Image Optimization</h2>
      <p>Astro Asset using Vercel Image Optimization</p>
    </hgroup>
    <AstroImage
      src={imageLight}
      alt="Light Screenshot"
      width={imageLight.width}
      height={imageLight.height}
      format={'webp'}
      quality={80}
      class="light"
    />
    <AstroImage
      src={imageDark}
      alt="Dark Screenshot"
      width={imageLight.width}
      height={imageLight.height}
      format={'webp'}
      quality={80}
      class="dark"
    />
  </section>
</Layout>

​
Image Formats

Vercel automatically serves images in optimal formats:
Modern format with excellent compression:
<AstroImage
  src={image}
  format="webp"
  quality={80}
/>

​
Quality Settings

Control image quality to balance file size and visual quality: 
<!-- High quality for hero images -->
<AstroImage src={hero} quality={90} />

<!-- Balanced quality for content images -->
<AstroImage src={content} quality={80} />

<!-- Lower quality for thumbnails -->
<AstroImage src={thumb} quality={60} />
A quality setting of 75-85 typically provides the best balance between file size and visual quality.

​
Responsive Images

Define multiple sizes for responsive images: 
<AstroImage
  src={image}
  widths={[320, 640, 1280]}
  sizes="(max-width: 640px) 100vw, (max-width: 1280px) 50vw, 1280px"
  alt="Responsive image"
/>
The browser automatically selects the appropriate size based on the viewport and device pixel ratio.

​
Local Images

Import and optimize local images: 
---
import { Image } from 'astro:assets'
import myImage from '../assets/my-image.jpg'
---

<Image
  src={myImage}
  alt="My image"
  width={800}
  height={600}
  format="webp"
  quality={80}
/>
Local images are automatically processed at build time and optimized for production.

​
Remote Images

Optimize images from external sources: 
<Image
  src="https://example.com/image.jpg"
  alt="Remote image"
  width={800}
  height={600}
  format="webp"
/>
Remote images must be from domains listed in domains or match a pattern in remotePatterns in your config.

​
Theme-Aware Images

Show different images based on color scheme: 
<AstroImage
  src={imageLight}
  alt="Light mode"
  class="light"
/>
<AstroImage
  src={imageDark}
  alt="Dark mode"
  class="dark"
/>

<style>
  @media (prefers-color-scheme: light) {
    img.dark {
      display: none;
    }
  }
  @media (prefers-color-scheme: dark) {
    img.light {
      display: none;
    }
  }
</style>

​
Performance Benefits

  • Automatic Format Selection: Serves WebP/AVIF to supporting browsers
  • Responsive Sizing: Generates multiple sizes for different viewports
  • Lazy Loading: Images load as they enter the viewport
  • CDN Caching: Optimized images are cached globally
  • On-Demand Processing: Images are optimized only when requested

​
Best Practices

  1. Always specify dimensions: Prevents layout shift
  2. Use appropriate quality: 75-85 for most images
  3. Choose the right format: WebP for general use, AVIF for maximum compression
  4. Enable lazy loading: Improves initial page load
  5. Optimize for mobile: Include smaller sizes in responsive configuration
Use the Network tab in browser DevTools to verify images are being served in optimized formats.

​
Next Steps

Analytics

Monitor image loading performance

SSR

Combine with SSR for dynamic images

Build docs developers (and LLMs) love

Get started for freeTalk to us