Nuxt Image v2 Released: Enhanced TypeScript, Performance, and New Providers

We are thrilled to announce the release of Nuxt Image v2! This major update, originally released on November 5, 2025, brings a host of enhancements, including comprehensive TypeScript support, an upgrade to IPX v3, and the introduction of new image providers, all aimed at boosting performance and improving the developer experience.

Authored by Daniel Roe @danielroe.dev

Nuxt Image v2 requires Nuxt 3.1+; users on Nuxt 3.0.x must upgrade to at least 3.1 first.

🎯 TypeScript support

The most significant enhancement in v2 is the integration of full TypeScript support across the entire module (#1802).

Typed composables

The $img helper and useImage() composable now offer complete type inference (#1844):

const img = useImage()
// Full autocomplete for modifiers
const url = img('/image.jpg', {
  width: 300,
  height: 200,
  fit: 'cover' // TypeScript knows the valid values!
})

Type-safe configuration

Module options are now fully typed. For example, providers requiring a baseURL will enforce this at the type level in your nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  image: {
    provider: 'bunny',
    bunny: {
      baseURL: '...' // TypeScript error if missing!
    }
  }
})

Typed providers

Finally, if you are using custom image providers, you should use the new defineProvider for type-safe configuration:

// Before (v1)
export const getImage = (src, { modifiers, baseURL }) => {
  // ...
  return { url }
}

// After (v2)
import { defineProvider } from '@nuxt/image/runtime'

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

🚀 IPX v3

We've upgraded to IPX v3 (#1799), leading to better performance and improved handling of sharp binaries. This upgrade includes automatic detection of the correct sharp binaries for your deployment architecture.

🔌 Server-side utilities

Image helpers can now be directly utilized within Nitro server endpoints (#1473):

// server/api/og-image.ts
export default defineEventHandler(
  (event) => {
    const img = useImage()
    return {
      url: img('/hero.jpg', {
        width: 1200,
        height: 630,
        fit: 'cover'
      })
    }
  }
)

🎨 Component improvements

Template refs

<NuxtImg> now exposes the underlying <img> element via template refs:

<script setup>
const img = useTemplateRef('img')
onMounted(() => {
  // Direct access to the native img element
  console.log(img.value.imgEl)
})
</script>

<template>
  <NuxtImg ref="img" src="/image.jpg"/>
</template>

Typed slots

Both <NuxtImg> and <NuxtPicture> components now feature properly typed default slots:

<template>
  <NuxtImg src="/image.jpg" custom>
    <template #default="{ imgAttrs, isLoaded, src }">
      <img v-bind="imgAttrs" :src="src">
      <span v-if="!isLoaded">Loading...</span>
    </template>
  </NuxtImg>
</template>

The slot provides:

• imgAttrs - All computed image attributes (sizes, srcset, etc.)
• isLoaded - Whether the placeholder has loaded
• src - The computed image source URL

🌐 New providers

Shopify

A new Shopify provider (#1890) is now available for configuration:

// nuxt.config.ts
export default defineNuxtConfig({
  image: {
    provider: 'shopify',
    shopify: {
      baseURL: 'https://your-store.myshopify.com'
    }
  }
})

GitHub

This provider allows injecting GitHub avatars and user content (#1990):

<!-- Width and height -->
<NuxtImg provider="github" src="nuxt" height="50" width="50"/>
<!-- Width only -->
<NuxtImg provider="github" src="unjs" width="512"/>
<!-- Default size -->
<NuxtImg provider="github" src="npm"/>

⚡ Performance

Several optimizations have been implemented to reduce bundle size and enhance runtime performance:

• Better URL encoding (#1813): Switched to URLSearchParams for more reliable parameter handling.
• Reduced runtime utilities (#1816): Unused code has been removed, and implementations simplified.
• Streamlined screen sizes (#1931): Default breakpoints now align with Tailwind CSS.

🎯 Better layer support

Nuxt Image now fully supports custom image directories within Nuxt layers (#1880), streamlining image organization in modular projects.

⚠️ Breaking changes

Please be aware of the following breaking changes:

Provider API

The most significant change is in how providers are defined. All providers now require a default export wrapped with the defineProvider wrapper:

- export const getImage = (src, { modifiers }) => { ... }
+ export default defineProvider({
+ name: 'my-provider',
+ getImage(src, { modifiers }) { ... }
+ })

If you maintain a custom provider, you'll need to update it. However, you gain full TypeScript support in return!

Removed providers

The deprecated layer0 and edgio providers have been removed.

URL formatters

If you have custom providers using joinWith for parameter formatting, you'll need to update them to use the formatter function with createOperationsGenerator. Refer to the migration guide for details.

Screen sizes

Default screen sizes now match Tailwind CSS. The xs (320px) and xxl (2560px) breakpoints have been removed. See the migration guide for how to add them back if needed.

Removed utilities

Several unused runtime utilities have been removed. If you were importing internal utilities directly, check if they still exist.

✅ Upgrading

For comprehensive upgrade instructions, consult our detailed migration guide.

The quick upgrade path:

npm install @nuxt/image@latest

Most applications can upgrade with no code changes. However, if you have custom providers, you'll need to update them to use defineProvider – see the migration guide for examples.

🐛 Bug fixes

This release also incorporates several important bug fixes:

• Preload links: Fixed preload for multiple densities with single size (#1851).
• Crossorigin attributes: Corrected crossorigin on preload links (#1836).
• Provider-specific formats: AWS Amplify and Vercel providers now have proper format allow lists (#1996).
• Hygraph: Prevented broken image URLs (#1999).
• Preset sizes: Fixed preset size application when component sizes prop is undefined (#1919).
• Cloudflare: Prevents adding baseURL if no operations are present (#1790).
• IPX: Always uses IPX provider if an external baseURL is provided (#1800).

🙏 Thank you

Our heartfelt thanks go to all contributors who made this release possible! This includes dozens of community members who contributed features, bug fixes, documentation improvements, and invaluable feedback.

📚 Resources

• Documentation
• GitHub Repository
• Migration Guide

👉 Full release notes

Read the full release notes for Nuxt Image v2.0.0.

Happy optimizing! 🖼️✨