1. The optimization process starts with your component choice in your codebase:
   • If you use a standard HTML img element, the browser will be instructed to bypass optimization and serve the image directly from its source.
   • If you use a framework's Image component (like next/image) 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 unoptimized prop on the Image component or the configuration in the next.config.ts file to determine if optimization is disabled.
   • If you set the unoptimized prop on the Image component to true, Next.js bypasses optimization and serves the image directly from its source.
   • If you don't set the unoptimized prop or set it to false, Next.js checks the next.config.ts file to see if optimization is disabled. This configuration applies to all images and overrides the individual component prop.
   • If neither the unoptimized prop is set nor optimization is disabled in the next.config.ts 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 ( remotePatterns or localPatterns).
4. Vercel then checks the status of the cache to see if an image has been previously cached:

• HIT: 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.
• MISS: 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.
• STALE: 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.

When to use Image Optimization

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 isn't beneficial, we recommend using the unoptimized prop on the Next.js Image 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 shouldn't use Image Optimization as these images are already small and optimizing them further wouldn't provide any benefits.

Setting up remote or local patterns

An important aspect of using the Image component is properly setting up remote/local patterns in your next.config.ts 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 public folder) and remote images (stored externally). In both cases you specify the pathname the images are located at.

Local 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}

Setting up local patterns

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

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

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

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

Remote images cache key

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

• Cache Key:
  • Project ID
  • Query string parameters:
    • q: The desired quality of the transformed image, between 1 (lowest quality) and 100 (highest quality).
    • w: The desired width (in pixels) of the transformed image.
    • url: The URL of the source image. Remote images use an absolute url (https://example.com/assets/me.png).
  • Accept 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 Cache-Control max-age header from the upstream image or minimumCacheTTL config (default: 3600 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.

Image Transformation URL format

When you use the Image component in common frameworks and deploy your project on Vercel, Image Optimization 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/src/image}&w=3840&q=75
• Nuxt, Astro, etc: /_vercel/image?url={link/to/src/image}&w=3840&q=75

The Image Optimization API has the following query parameters:

• url: The URL of the source image to be transformed. This can be a local image (relative url) or remote image (absolute url).
• w: The width of the transformed image in pixels. No height is needed since the source image aspect ratio is preserved.
• q: 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're using, such as next.config.js for Next.js.

If you aren't using a framework that comes with an Image component or you're 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.

Opt-in

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

Image optimization from the CLI

The use case above is request-driven: images are transformed when a browser requests them through your deployment's public API. You can also optimize an image once at write time and store the result in Vercel Blob, without a deployed app or allowlist configuration:

• From the terminal, run vercel blob put-image. The command prints the URL of the stored image to stdout, so scripts and agents can read the result back.
• In code, call putImage() from the @vercel/blob SDK.