---
title: "Migration to v2"
description: "A comprehensive guide to migrate your application from Nuxt Image v1 to Nuxt Image v2."
canonical_url: "https://nuxt.com/modules/image/migration"
---
# 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:

::code-group{sync="pm"}
```bash [pnpm]
pnpm add @nuxt/image
```

```bash [yarn]
yarn add @nuxt/image
```

```bash [npm]
npm install @nuxt/image
```

```bash [bun]
bun add @nuxt/image
```

```bash [deno]
deno add npm:@nuxt/image
```
::

## Check your Nuxt version

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

```bash
npm list nuxt
```

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

```bash
npx nuxt upgrade --channel v3
```

::tip
Nuxt Image v2 is fully compatible with Nuxt 4. See the [Nuxt 4 migration guide](https://nuxt.com/docs/4.x/getting-started/upgrade#migrating-to-nuxt-4) 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:

```bash
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`:

```diff
  <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:

```ts [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):**

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

**After (v2):**

```ts [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:

```ts [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.

```ts [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}`
    }
  }
})
```


## Sitemap

See the full [sitemap](https://nuxt.com/sitemap.md) for all pages.