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 very 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.

React Component

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).

Those variations will then be requested from the Edge Network.

Note: Image Optimization requires Next.js version 10 or newer.

Required Parameters

In order for the component to work, at least the src, width and height parameters need to be passed. This will guarantee the image is optimized and layout shifts are avoided.

If you don't have the size available, you can also pass unsized instead of width and height. However, visual stability will not be guaranteed in that case.

You can find more details about all the other additional parameters you can pass to the component in the Next.js documentation.

External URLs

As you can see, the example shown above contains the path of an image that was added to the Deployment on Vercel (it's a relative path, not a full URL).

While this might be useful for a basic application, we generally recommend loading content (which also includes images) from a headless CMS like Sanity. That service will then provide you with entire URLs that you can place in the src parameter.

Note: Serving images from an external URL requires custom configuration.

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 (using the example shown in the React Component section above), the Edge Network 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 in the respective node in your Edge Network. This means that, on subsequent request, the cached version will be served (considering that the parameters passed to the component didn't change).

Configuration

Using the Image component with a relative path (which therefore points to an image on your Deployment) doesn't require any additional configuration.

If you'd like to use external URLs, however (which Vercel recommends if you have a lot of images), you need to pass an additional images property in your next.config.js file, as shown in this example.

In general, you can customize the behavior of the React Component by passing additional parameters to it.

Customizing the behavior of the Edge Network Optimization, however, requires passing the images property in your next.config.js file.

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.


Last Edited on October 26th 2020