Image Optimization with Vercel

Vercel supports dynamically transforming unoptimized images to reduce the file size while maintaining high quality. These optimized images are cached on the Vercel CDN, meaning they're available close to users whenever they're requested.

Image Optimization works with many frameworks, including Next.js, Astro, and Nuxt, enabling you to optimize images using built-in components.

• Get started by following the Image Optimization Quickstart and selecting your framework (Next.js, Nuxt, or Astro) from the dropdown.
• For a live example which demonstrates usage with the component, see the Image Optimization demo.

Optimizing images on Vercel provides several advantages for your application:

• Reduces the size of images and data transferred, enhancing website performance, user experience, and Fast Data Transfer usage.
• Improving Core Web Vitals, reduced bounce rates, and speeding up page loads.
• Sizing images to support different devices and use modern formats like WebP and AVIF.
• Optimized images are cached after transformation, which allows them to be reused in subsequent requests.

The flow of image optimization on Vercel involves several steps, starting from the image request to serving the optimized image.

1. The optimization process starts with your component choice in your codebase:

   • If you use a standard HTML element, the browser will be instructed to bypass optimization and serve the image directly from its source.
   • If you use a framework's component (like ) it will use Vercel's image optimization pipeline, allowing your images to be automatically optimized and cached.

2. When Next.js receives an image request, it checks the prop on the component or the configuration in the file to determine if optimization is disabled.

   • If you set the prop on the component to , Next.js bypasses optimization and serves the image directly from its source.
   • If you don't set the prop or set it to , Next.js checks the file to see if optimization is disabled. This configuration applies to all images and overrides the individual component prop.
   • If neither the prop is set nor optimization is disabled in the file, Next.js continues with the optimization process.

3. If optimization is enabled, Vercel validates the loader configuration (whether using the default or a custom loader) and verifies that the image source URL matches the allowed patterns defined in your configuration ( or ).

4. Vercel then checks the status of the cache to see if an image has been previously cached:

• : The image is fetched and served from the cache, either in region or from the shared global cache.
  • If fetched from the global cache, it's billed as an image cache read which is reflected in your usage metrics.
• : The image is fetched, transformed, cached, and then served to the user.
  • Billed as an image transformation and image cache write which is reflected in your usage metrics.
• : The image is fetched and served from the cache while revalidating in the background.
  • Billed as an image transformation and image cache write which is reflected in your usage metrics.

Image Optimization is ideal for:

• Responsive layouts where images need to be optimized for different device sizes (e.g. mobile vs desktop)
• Large, high-quality images (e.g. product photos, hero images)
• User uploaded images
• Content where images play a central role (e.g. photography portfolios)

In some cases, Image Optimization may not be necessary or beneficial, such as:

• Small icons or thumbnails (under 10 KB)
• Animated image formats such as GIFs
• Vector image formats such as SVG
• Frequently changing images where caching could lead to outdated content

If your images meet any of the above criteria where Image Optimization is not beneficial, we recommend using the prop on the Next.js component. For guidance on SvelteKit, Astro, or Nuxt, see their documentation.

It's important that you are only optimizing images that need to be optimized otherwise you could end up using your image usage quota unnecessarily. For example, if you have a small icon or thumbnail that is under 10 KB, you should not use Image Optimization as these images are already very small and optimizing them further would not provide any benefits.

An important aspect of using the component is properly setting up remote/local patterns in your file. This configuration determines which images are allowed to be optimized.

You can set up patterns for both local images (stored as static assets in your folder) and remote images (stored externally). In both cases you specify the pathname the images are located at.

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

To set up local patterns, you need to specify the pathname of the images you want to optimize. This is done in the file:

See the Next.js documentation for local patterns for more information.

The cache key for local images is based on the query string parameters, the HTTP header, and the content hash of the image URL.

• Cache Key:
  • Project ID
  • Query string parameters:
    • : The desired quality of the transformed image, between 1 (lowest quality) and 100 (highest quality).
    • : The desired width (in pixels) of the transformed image.
    • : The URL of the source image. For local images () the content hash is used instead ().
  • 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.
  • You can also manually purge or programatically purge to invalidate all cached transformations of a source image without redeploying.
• Local image cache expiration:
  • Cached for up to 31 days on the Vercel CDN.

A remote image requires the property to be a URL string, which can be relative or absolute.

To set up remote patterns, you need to specify the of the images you want to optimize. This is done in the file:

In the case of external images, you should consider adding your account id to the if you don't own the . For example . This helps protect your source images from potential abuse.

See the Next.js documentation for remote patterns for more information.

The cache key for remote images is based on the query string parameters, the HTTP header, and the content hash of the image URL.

• Cache Key:
  • Project ID
  • Query string parameters:
    • : The desired quality of the transformed image, between 1 (lowest quality) and 100 (highest quality).
    • : The desired width (in pixels) of the transformed image.
    • : The URL of the source image. Remote images use an absolute url ().
  • HTTP header (normalized).
• Remote image cache invalidation:
  • Redeploying your app doesn't invalidate the image cache
  • You can manually purge or programatically purge to invalidate all cached transformations of a source image without redeploying.
  • Alternatively, you can configure the cache to expire more frequently by adjusting the TTL.
• Remote image cache expiration:
  • TTL is determined by the header from the upstream image or config (default: seconds), whichever is larger.

Once an image is cached, it remains so even if you update the source image. For remote images, users accessing a URL with a previously cached image will see the old version until the cache expires or the image is invalidated. Each time an image is requested, it counts towards your Fast Data Transfer and Edge Request usage for your billing cycle.

See Pricing for more information, and read more about caching behavior in the Next.js documentation.

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

• Next.js:
• Nuxt, Astro, etc:

The Image Optimization API has the following query parameters:

• : The URL of the source image to be transformed. This can be a local image (relative url) or remote image (absolute url).
• : The width of the transformed image in pixels. No height is needed since the source image aspect ratio is preserved.
• : The quality of the transformed image, between 1 (lowest quality) and 100 (highest quality).

The allowed values of those query parameters are determined by the framework you are using, such as for Next.js.

If you are not using a framework that comes with an component or you are building your own framework, refer to the Build Output API to see how the build output from a framework can configure the Image Optimization API.

To switch to the transformation images-based pricing plan:

1. Choose your team scope on the dashboard, and go to Settings, then Billing
2. Scroll down to the Image Optimization section
3. Select Review Cost Estimate. Proceed to enable this option in the dialog that shows the cost estimate.

View your estimate

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

• Image Optimization quickstart
• Managing costs
• Pricing
• 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.