Get Started

Migration to v2

A comprehensive guide to migrate your application from Nuxt Image v1 to Nuxt Image v2.

Nuxt Image v2 brings improved performance, enhanced TypeScript support, and a better developer experience.

Most apps should be able to upgrade with minimal changes.

Update dependencies

Update @nuxt/image to v2:

pnpm add @nuxt/image

Check your Nuxt version

Nuxt Image v2 requires at least Nuxt 3.1. Check your current version:

npm list nuxt

If you're on Nuxt 3.0.x, upgrade first:

npx nuxt upgrade --channel v3
Nuxt Image v2 is fully compatible with Nuxt 4. See the Nuxt 4 migration guide if you're ready to upgrade.

Update screen sizes

The xs and xxl breakpoints have been removed to align with Tailwind CSS defaults.

Search for usage in your project:

grep -r "sizes.*xs:" --include="*.vue"
grep -r "sizes.*xxl:" --include="*.vue"

If you are using these screen sizes, you can either replace xs with sm and xxl with 2xl:

  <NuxtImg 
    src="/image.jpg" 
-   sizes="xs:100vw sm:50vw md:400px"
+   sizes="sm:100vw md:50vw lg:400px"
  />

... or you can add them back in your config:

nuxt.config.ts
export default defineNuxtConfig({
  image: {
    screens: {
      xs: 320,
      xxl: 1536
    }
  }
})

Update custom providers

If you have custom image providers, update them to use defineProvider.

Before (v1):

providers/my-provider.ts
export const getImage = (src, { modifiers }) => {
  // ...
  return { url }
}

After (v2):

providers/my-provider.ts
import { defineProvider } from '@nuxt/image/runtime'

export default defineProvider({
  getImage(src, { modifiers }) {
    // ...
    return { url }
  }
})

Add modifier types (optional)

Add types for custom modifiers:

providers/my-provider.ts
import { defineProvider } from '@nuxt/image/runtime'
import type { ImageModifiers } from '@nuxt/image'

interface MyProviderModifiers extends ImageModifiers {
  watermark?: 'logo' | 'text' | 'none'
  rotate?: number
}

export default defineProvider<MyProviderModifiers>({
  getImage(src, { modifiers }) {
    // ...
    return { url }
  }
})

Modifiers will now be typed within your provider, and also when it is used within <NuxtImg> and <NuxtPicture>.

Update formatter

Within createOperationsGenerator, if you used joinWith for parameter formatting, but didn't use formatter, you will now need to add a custom formatter.

providers/my-provider.ts
import { createOperationsGenerator, defineProvider } from '@nuxt/image/runtime'

const operationsGenerator = createOperationsGenerator({
  keyMap: { width: 'w', height: 'h' },
  joinWith: '&',
  formatter: (key, value) => `${key}=${encodeURIComponent(value)}`
})

export default defineProvider({
  getImage(src, { modifiers, baseURL = '/' }) {
    const operations = operationsGenerator(modifiers)
    return {
      url: `${baseURL}${src}?${operations}`
    }
  }
})

Contributing

We can never thank you enough for your contributions.

<NuxtImg>

Discover how to use and configure the Nuxt Image component.