--- title: Getting started with Image Optimization product: vercel url: /docs/image-optimization/quickstart canonical_url: "https://vercel.com/docs/image-optimization/quickstart" last_updated: 2026-08-11 type: tutorial prerequisites: - /docs/image-optimization related: - /docs/cdn - /docs/image-optimization/limits-and-pricing - /docs/image-optimization/managing-image-optimization-costs summary: Learn how you can leverage Vercel Image Optimization in your projects. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Getting started with Image Optimization This guide will help you get started with using Vercel Image Optimization in your project, showing you how to import images, add the required props, and deploy your app to Vercel. Vercel Image Optimization works out of the box with Next.js, Nuxt, SvelteKit, and Astro. ## Related pages > **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below. - [OG Image Generation: The Complete Customization Guide](https://vercel.com/kb/guide/using-custom-font) — Learn how to use custom fonts in your Vercel OG image, plus emoji, external images, non-Latin text, dynamic titles, and - [How to Optimize Next.js + Sitecore JSS](https://vercel.com/kb/guide/how-to-optimize-next.js-sitecore-jss) — This guide covers performance and usage considerations when building and deploying your Next.js and Sitecore JSS applica - [How to reduce Vercel Image Optimization costs](https://vercel.com/kb/guide/reduce-image-optimization-costs-on-vercel) — Learn how to reduce Vercel Image Optimization costs in Next.js by tuning cache TTLs, image sizes, formats, and quality. - [How do I reduce my build time with Next.js on Vercel?](https://vercel.com/kb/guide/how-do-i-reduce-my-build-time-with-next-js-on-vercel) — Reduce Next.js build times on Vercel by pre-rendering fewer pages at build time, deferring generation with ISR and image - [Building a fast, animated image gallery with Next.js](https://vercel.com/blog/building-a-fast-animated-image-gallery-with-next-js) - [The Next.js SEO Playbook: Ranking higher with Next.js on Vercel](https://vercel.com/blog/nextjs-seo-playbook) - [How to Integrate Optimizely Feature Experimentation with Next.js and Vercel](https://vercel.com/kb/guide/how-to-integrate-optimizely-feature-experimentation-next-vercel) — This guide covers setting up feature flags, implementing A/B tests, and optimizing performance using React Server Compon - [Getting started with Speed Insights](https://vercel.com/docs/speed-insights/quickstart) — Vercel Speed Insights provides you detailed insights into your website's performance. This quickstart guide will help yo - [Getting started with Vercel Web Analytics](https://vercel.com/docs/analytics/quickstart) — Vercel Web Analytics provides you detailed insights into your website's visitors. This quickstart guide will help you ge - [Supported Frameworks on Vercel](https://vercel.com/docs/frameworks/more-frameworks) — Learn about the frameworks that can be deployed to Vercel. - [Vercel and Sitecore XM Cloud Integration](https://vercel.com/docs/integrations/cms/sitecore) — Integrate Vercel with Sitecore XM Cloud to deploy your content. - [Astro on Vercel](https://vercel.com/docs/frameworks/frontend/astro) — Deploy Astro sites to Vercel and configure server-side rendering, ISR, Web Analytics, Image Optimization, and Routing Mi Full cross-link map for this page: [/docs/image-optimization/quickstart.graph.md](/docs/image-optimization/quickstart.graph.md) **Agent prompt** ```text Help me set up image optimization in this project. First, make sure the Vercel CLI is installed (`npm i -g vercel`). If I'm using Claude Code or Cursor, install the Vercel Plugin (`npx plugins add vercel/vercel-plugin`). For other agents, install Vercel Skills (`npx skills add vercel-labs/agent-skills`). Then: 1. Use the next/image component (or Vercel image optimization for other frameworks) to serve optimized images with automatic format conversion and resizing. 2. Deploy with `vercel --prod` to verify images are optimized. ``` ## Prerequisites - A Vercel account. If you don't have one, you can [sign up for free](https://vercel.com/signup). - A Vercel project. If you don't have one, you can [create a new project](https://vercel.com/new). - The Vercel CLI installed. If you don't have it, you can install it using the following command: **pnpm** ```bash pnpm i -g vercel ``` **yarn** ```bash yarn global add vercel ``` **npm** ```bash npm i -g vercel ``` **bun** ```bash bun add -g vercel ``` - ### Import images > For \['astro']: To use Astro, you must: 1. Enable [Vercel's image service](https://docs.astro.build/en/guides/integrations-guide/vercel/#imageservice) in `astro.config.ts` ```js filename="astro.config.mjs" framework=all import { defineConfig } from 'astro/config'; import vercel from '@astrojs/vercel/static'; export default defineConfig({ output: 'server', adapter: vercel({ imageService: true, }), }); ``` ```ts filename="astro.config.mjs" framework=all import { defineConfig } from 'astro/config'; import vercel from '@astrojs/vercel/static'; export default defineConfig({ output: 'server', adapter: vercel({ imageService: true, }), }); ``` 2. Use Astro's built-in `Image` component: ```jsx filename="src/components/MyComponent.astro" framework=all --- // import the Image component and the image import { Image } from 'astro:assets'; import myImage from "../assets/my_image.png"; // Image is 1600x900 --- {/* `alt` is mandatory on the Image component */} A description of my image. ``` ```tsx filename="src/components/MyComponent.astro" framework=all --- // import the Image component and the image import { Image } from 'astro:assets'; import myImage from "../assets/my_image.png"; // Image is 1600x900 --- {/* `alt` is mandatory on the Image component */} A description of my image. ``` > For \['nextjs']: Next.js provides a built-in [`next/image`](https://nextjs.org/docs/pages/api-reference/components/image) component. ```js filename="pages/index.js" framework=all import Image from 'next/image'; ``` ```ts filename="pages/index.ts" framework=all import Image from 'next/image'; ``` > For \['sveltekit']: To use SvelteKit, use [`@sveltejs/adapter-vercel`](https://kit.svelte.dev/docs/adapter-vercel) within your `svelte.config.ts` file. ```js filename="svelte.config.js" framework=all import adapter from '@sveltejs/adapter-vercel'; export default { kit: { adapter: adapter({ images: { sizes: [640, 828, 1200, 1920, 3840], formats: ['image/avif', 'image/webp'], minimumCacheTTL: 300, domains: ['example-app.vercel.app'], }, }), }, }; ``` ```ts filename="svelte.config.ts" framework=all import adapter from '@sveltejs/adapter-vercel'; export default { kit: { adapter: adapter({ images: { sizes: [640, 828, 1200, 1920, 3840], formats: ['image/avif', 'image/webp'], minimumCacheTTL: 300, domains: ['example-app.vercel.app'], }, }), }, }; ``` This allows you to specify [configuration options](https://vercel.com/docs/build-output-api/configuration#images) for Vercel's native image optimization API. You have to construct your own `srcset` URLs to use image optimization with SvelteKit. You can create a library function that will optimize `srcset` URLs in production for you like this: ```js filename="src/lib/image.js" framework=all import { dev } from '$app/environment'; export function optimize(src, widths = [640, 960, 1280], quality = 90) { if (dev) return src; return widths .slice() .sort((a, b) => a - b) .map((width) => { const url = `/_vercel/image?url=${encodeURIComponent(src)}&w=${width}&q=${quality}`; return `${url} ${width}w`; }) .join(', '); } ``` ```ts filename="src/lib/image.ts" framework=all import { dev } from '$app/environment'; export function optimize(src: string, widths = [640, 960, 1280], quality = 90) { if (dev) return src; return widths .slice() .sort((a, b) => a - b) .map((width) => { const url = `/_vercel/image?url=${encodeURIComponent(src)}&w=${width}&q=${quality}`; return `${url} ${width}w`; }) .join(', '); } ``` > For \['nextjs-app']: Next.js provides a built-in [`next/image`](https://nextjs.org/docs/app/api-reference/components/image) component. ```js filename="app/example/page.jsx" framework=all import Image from 'next/image'; ``` ```ts filename="app/example/page.tsx" framework=all import Image from 'next/image'; ``` > For \['nuxt']: Install the `@nuxt/image` package: **pnpm** ```bash pnpm i @nuxt/image ``` **yarn** ```bash yarn add @nuxt/image ``` **npm** ```bash npm i @nuxt/image ``` **bun** ```bash bun add @nuxt/image ``` Then, add the module to the `modules` array in your Nuxt config: ```js filename="nuxt.config.js" framework=all export default defineNuxtConfig({ modules: ['@nuxt/image'], }); ``` ```ts filename="nuxt.config.ts" framework=all export default defineNuxtConfig({ modules: ['@nuxt/image'], }); ``` When you deploy to Vercel, the Vercel provider will be automatically enabled by default. **Vercel requires you to explicitly list all the widths used in your app** for proper image resizing: ```js filename="nuxt.config.js" framework=all export default defineNuxtConfig({ modules: ['@nuxt/image'], image: { // You must specify every custom width used in , or $img screens: { xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, xxl: 1536, // Add any custom widths used in your components avatar: 40, avatar2x: 80, hero: 1920, }, // Whitelist external domains for images not in public/ directory domains: ['example.com', 'images.unsplash.com'], }, }); ``` ```ts filename="nuxt.config.ts" framework=all export default defineNuxtConfig({ modules: ['@nuxt/image'], image: { // You must specify every custom width used in , or $img screens: { xs: 320, sm: 640, md: 768, lg: 1024, xl: 1280, xxl: 1536, // Add any custom widths used in your components avatar: 40, avatar2x: 80, hero: 1920, }, // Whitelist external domains for images not in public/ directory domains: ['example.com', 'images.unsplash.com'], }, }); ``` **Important:** If a width is not defined in your configuration, the image will fallback to the next bigger width, which may affect performance and bandwidth usage. See the [Nuxt Image documentation](https://image.nuxt.com/providers/vercel) for more details on Vercel provider requirements and [configuration options](https://image.nuxt.com/get-started/configuration). - ### Add the required props > For \['astro']: The only required props for Astro's `Image` component are `alt` and `src`. All other attributes are enforced automatically if not specified. Given the following `.astro` file: ```jsx filename="src/components/MyComponent.astro" framework=all --- // import the Image component and the image import { Image } from 'astro:assets'; import myImage from "../assets/my_image.png"; // Image is 1600x900 --- {/* `alt` is mandatory on the Image component */} A description of my image. ``` ```tsx filename="src/components/MyComponent.astro" framework=all --- // import the Image component and the image import { Image } from 'astro:assets'; import myImage from "../assets/my_image.png"; // Image is 1600x900 --- {/* `alt` is mandatory on the Image component */} A description of my image. ``` The output would look like this: ```tsx filename="src/components/MyComponent.astro" framework=all { /* Output */ } { /* Image is optimized, proper attributes are enforced */ } A description of my image.; ``` ```jsx filename="src/components/MyComponent.astro" framework=all { /* Output */ } { /* Image is optimized, proper attributes are enforced */ } A description of my image.; ``` > For \['nextjs']: This component takes the following [required props](https://nextjs.org/docs/pages/api-reference/components/image#required-props): - `src`: The URL of the image to be loaded - `alt`: A short description of the image - `width`: The width of the image - `height`: The height of the image When using [local images](https://nextjs.org/docs/pages/api-reference/components/image#local-images "Local images") you **do not** need to provide the `width` and `height` props. These values will be automatically determined based on the imported image. The below example uses a [remote image](https://nextjs.org/docs/pages/api-reference/components/image#remote-images "Remote Images") with the `width` and `height` props applied: ```js filename="pages/index.jsx" framework=all Picture of a triangle ``` ```ts filename="pages/index.tsx" framework=all Picture of a triangle ``` If you have images with URLs that may change frequently, even if the image content remains the same, you might want to avoid optimization. This is often the case with URLs containing unique identifiers or tokens. To disable image optimization for such images, use the [`unoptimized`](https://nextjs.org/docs/pages/api-reference/components/image#unoptimized) prop. For more information on all props, caching behavior, and responsive images, visit the [`next/image`](https://nextjs.org/docs/pages/api-reference/components/image) documentation. > For \['sveltekit']: To use image optimization with SvelteKit, you can use the `img` tag or any image component. Use an optimized `srcset` string generated by your `optimize` function: ```tsx filename="src/components/image.svelte" framework=all {photo.description} ``` ```jsx filename="src/components/image.svelte" framework=all {photo.description} ``` > For \['nextjs-app']: This component takes the following [required props](https://nextjs.org/docs/app/api-reference/components/image#required-props): - `src`: The URL of the image - `alt`: A short description of the image - `width`: The width of the image - `height`: The height of the image When using [local images](https://nextjs.org/docs/app/getting-started/images#local-images "Local images") you **do not** need to provide the `width` and `height` props. These values will be automatically determined based on the imported image. The example below uses a [remote image](https://nextjs.org/docs/app/getting-started/images#remote-images "Remote Images") with the `width` and `height` props applied: ```js filename="app/example/page.jsx" framework=all Triangular frames arranged concentrically, creating a tunnel against a dark background. ``` ```ts filename="app/example/page.tsx" framework=all Triangular frames arranged concentrically, creating a tunnel against a dark background. ``` If there are some images that you wish to not optimize (for example, if the URL contains a token), you can use the [unoptimized](https://nextjs.org/docs/app/api-reference/components/image#unoptimized) prop to disable image optimization on some or all of your images. For more information on all props, caching behavior, and responsive images, visit the [`next/image`](https://nextjs.org/docs/app/api-reference/components/image) documentation. > For \['nuxt']: The `` component will automatically optimize your images on demand. It is a wrapper around the `` element, and takes all of its standard props, such as `src` and `alt`. It also takes a set of special props for Image Optimization. You can see the full list in [the Nuxt documentation](https://image.nuxt.com/usage/nuxt-img#props). The following example demonstrates a `` component with optimization props: ```jsx filename="pages/index.vue" framework=all ``` ```tsx filename="pages/index.vue" framework=all ``` - ### Deploy your app to Vercel > For \['nextjs', 'nextjs-app']: Push your changes and deploy your Next.js application to Vercel. When deployed to Vercel, this component automatically optimizes your images on-demand and serves them from the [Vercel CDN](/docs/cdn). > For \['sveltekit']: Push your changes and deploy your SvelteKit application to Vercel. Your images that use optimized `src` URLs will leverage Vercel's on-demand image optimization. Images get served from the [Vercel CDN](/docs/cdn). > For \['astro']: Push your changes and deploy your Astro application to Vercel. When deployed to Vercel, this component automatically optimizes your images on-demand and serves them from the [Vercel CDN](/docs/cdn). > For \['nuxt']: When you deploy your Nuxt application to Vercel, the Vercel provider will be automatically enabled by default and use Vercel's CDN for on-demand image optimization. The `` components will automatically optimize your images and serve them from the [Vercel CDN](/docs/cdn). Make sure you have configured the required image widths and whitelisted any external domains as shown in the configuration above. For more information on usage with external URLs and customizing your images on demand, visit the [`@nuxt/image`](https://image.nuxt.com/providers/vercel) documentation. ## Next steps Now that you've set up Vercel Image Optimization, you can explore the following: - [Explore limits and pricing](/docs/image-optimization/limits-and-pricing) - [Managing costs](/docs/image-optimization/managing-image-optimization-costs) --- [View full sitemap](/docs/sitemap) If you encounter incorrect information, can’t find what you need, need a capability Vercel doesn’t currently offer, or have any other feedback to report, please do it by following the instructions at https://vercel.com/feedback.md.