When adding images to a web application, it's essential for a great user experience that they're served as fast as possible and appear without a layout shift.

Vercel makes it easy to accomplish ideal loading times and prevent layout shifts for images when deploying Next.js applications by providing you with a built-in next/image component that automatically optimizes your images on demand and serves them from our globally distributed Edge Network.

Usage

Once you've deployed your Next.js application to Vercel, ensuring that your images are automatically optimized by Vercel's Edge Network is only a matter of importing Next.js' native Image component:

import Image from 'next/image';

Afterwards, pass the URL of the image, the size, and an explanation of what it shows:

<Image
  src="/images/vercel-logo.png"
  alt="Picture of a triangle"
  width={500}
  height={500}
/>

Once deployed, the component will dynamically serve different variations of your image for common device screen sizes used by visitors on the web (you can find the default list of sizes and information on how to adjust them here).

You can also use next/image with remote images, instead of those located inside your repository. To learn more about configuration and usage, check out the Next.js documentation.

Edge Network Optimization

All the variations of your image requested by the Image component will automatically be prefixed with /_next/image?url=, which ensures that Vercel's Edge Network automatically optimizes them on demand.

The first time a new image is requested from the Edge Network, all the transformations outlined in the parameters passed to the component are applied.

By default, Vercel will dynamically generate a new image for all of the variations requested by the Image component. Afterwards, the file size of each image is reduced by optimizing the quality of the image.

Lastly, the image variations are served and cached on Vercel's Edge Network. This means that on subsequent requests the cached version will be served (assuming that the parameters passed to the component didn't change).

Even if you redeploy, images cached in /_next/image will be preserved.

Vercel creates a cache key using the following:

  • Content hash for static images (or external URL for remote images)
  • Query String parameters (w, q, etc.)
  • Accept HTTP header

This ensures that browsers with support for WebP can utilize the same Edge Cache.

Measuring Performance

Before you adopt Image Optimization in an existing project, enable Analytics for it.

This will allow you to measure real-world performance & user experience over time and compare the before and after Image Optimization.

Source Images

A Source Image is the original, unaltered image determined by the src prop.

When the src prop is an internal path (an image in the current deployment), the file contents are hashed to determine the Source Image.

When the src prop is an external URL (an image hosted elsewhere), the URL is used to determine the Source Image.

A single Source Image can be transformed into many Optimized Images. Take the following for example:

  • Usage: <Image src="/hero.png" width="700" height="745" />
  • Source Image: /hero.png
  • Optimized Image: /_next/image?url=%2Fhero.png&w=750&q=75
  • Optimized Image: /_next/image?url=%2Fhero.png&w=828&q=75
  • Optimized Image: /_next/image?url=%2Fhero.png&w=1080&q=75

The Usage page will reset the Source Image count each month. For example, a deployment with 50 png files will see 50 Source Images used each month. Deleting a png file will still show 50 Source Images for the current month, but the next month will show 49 Source Images.

Next.js projects that configure the loader config or unoptimized prop will opt out of Vercel Image Optimization in favor of a 3rd party image provider. Therefore, the Usage page will show 0 Source Images each month.

Next.js projects that configure the domains config will likely see a high number of Source Images, especially if users of the website can upload arbitrary images that will be optimized. This is because the use of the domains property will mean images from external sites may also be optimized.

Limits

For all the images that are optimized by Vercel, the following limits apply:

If no max-age value is provided in a Cache-Control header returned by the image URL/path, a default max-age of 60 seconds is set. In turn, source images will be retrieved again and optimized on incoming requests if more than 60 seconds have passed since the last optimization of that image (in the same Edge Network node).

Additionally, the maximum width and height of each source image is 8192 pixels.

Only the following file formats can be optimized by Vercel:

  • .bmp
  • .ico
  • .icns
  • .jpeg
  • .pct
  • .png
  • .tiff
  • .webp

Also see the Fair Usage Policy for monthly usage limits.


Last Edited on July 16th 2021