3 min read

Image Optimization with Vercel

Vercel has built-in image optimization that automatically serves the optimal image to your visitors.
Table of Contents

Image Optimization is available on all plans

Vercel streamlines the image optimization process and manages the infrastructure for uploading, optimizing, and delivering images based on factors like pixel density, format, size, and quality. These optimized images are cached on the Vercel Edge Network, ensuring swift delivery to users.

Some popular frameworks, including Next.js, Astro, and Nuxt seamlessly integrate with Vercel's Image Optimization, enabling you to optimize images using built-in components.

For a live example which demonstrates usage with the next/image component, see the Image Optimization demo.

To start using Image Optimization with Next.js, Astro, or Nuxt, follow the quickstart.

If you are building a custom web framework, you can also use the Build Output API to implement Image Optimization. To learn how to do this, see the Build your own web framework blog post.

When you use the Images component in common frameworks and deploy your project on Vercel, the Image Optimization feature automatically adjusts your images for different device screen sizes. The src prop you provided in your code is dynamically replaced with an optimized image URL. For example:

  • Next.js: /_next/image?url={link/to/my/image}&w=3840&q=75
  • Nuxt.js or Astro: /_vercel/image?url={link/to/my/image}&w=3840&q=75
  • Build Output API: /_vercel/image?url={link/to/my/image}&w=3840&q=75

Optimized images are automatically cached on the Vercel Edge Network and subsequent requests to the same image will be served from the cache. The caching behavior is different for local images compared to remote images:

A local image is imported from your file system and analyzed at build time. The import is added to the src prop: src={myImage}

  • Cache Key:
    • Query string parameters:
      • q: The quality of the optimized image, between 1 (lowest quality) and 100 (highest quality).
      • w: The width (in pixels) of the optimized image
      • url: The URL of the optimized image is keyed by content hash e.g. /assets/me.png is converted to 3399d02f49253deb9f5b5d1159292099
    • Accept HTTP header (normalized)
  • Local image cache invalidation:
    • Redeploying your app doesn't invalidate the image cache
    • To invalidate, replace the image of the same name with different content, then redeploy
  • Local image cache expiration:
    • Cached for up to 31 days on the Edge Network

A remote image requires the src property to be a URL string, which can be relative or absolute. As Next.js doesn't have access to remote files during the build process, the width and height props are needed.

  • Cache key:
    • Query string parameters:
      • q: The quality of the optimized image, between 1 (lowest quality) and 100 (highest quality).
      • w: The width (in pixels) of the optimized image
      • url: The URL of the optimized image e.g. https://example.com/assets/me.png
    • Accept HTTP header (normalized)
  • Remote image cache invalidation:
    • Redeploying your app doesn't invalidate the image cache
    • To invalidate, add a query string to the src property (e.g., ?v=2), then redeploy
    • Alternatively, you can configure the cache to expire more frequently
  • Remote image cache expiration:
    • TTL is determined by the Cache-Control max-age header from the upstream image or minimumCacheTTL config (default: 60 seconds), whichever is larger
    • If your image content changes frequently, it's best to keep this TTL short

Refer to the Limits and Pricing page for more information. Measure real-world performance using Speed Insights before and after adopting Image Optimization.

Optimizing images on Vercel provides several advantages for your application:

  • Enhanced website performance, user experience, and Fast Data Transfer savings
  • Improved Core Web Vitals, reduced bounce rates, and faster page loads
  • Properly sized images for different devices and support for modern formats like WebP and AVIF
  • When source images cannot be optimized, Vercel will fall back to serving the original image
  • Vercel manages the infrastructure for generating and caching optimized images at the Edge for quick responses

For more information on what to do next, we recommend the following articles:

Last updated on June 19, 2024