@nuxt/image
2.2.1 · 30 Oct 2026MIT817.3k / weekRepositoryHomepagenpmAtom feed
2.2.1 is the newest release of 2.x.
In short
6 breaking15 new4 faster18 fixed52 internal
- Breaking
The biggest breaking change is how providers are defined.
- Breaking
⚠️ Typed providers + modifiers
- Breaking
edgio,layer0: ⚠️ Remove providers
- Breaking
⚠️ Use URLSearchParams as default formatter
- Breaking
⚠️ Remove unused runtime utilities and simplify code
- Breaking
⚠️ Remove xs and xxl screen sizes
Release note
We're excited to announce Nuxt Image v2! 🎉 This release focuses on TypeScript support, performance improvements, and better developer experience.
Highlights
Note
Nuxt Image v2 requires Nuxt 3.1+. If you're on Nuxt 3.0.x, you'll need to upgrade to at least 3.1 first.
TypeScript support
The biggest change in v2 is full TypeScript support throughout the module (#1802).
Typed providers
Image providers now use 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 }
}
})Type-safe configuration
Module options are now fully typed. For example, providers that require a baseURL will enforce it at the type level in your nuxt.config.ts:
export default defineNuxtConfig({
image: {
provider: 'cloudinary',
cloudinary: {
baseURL: 'https://res.cloudinary.com/...' // TypeScript error if missing!
}
}
})Typed composables
The $img helper and useImage() composable have full 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!
})IPX v3
We've upgraded to IPX v3 (#1799) for better performance and better sharp binary handling. The upgrade includes automatic detection of the correct sharp binaries for your deployment architecture.
Server-side utilities
You can now use image helpers directly in 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> now have properly typed default slots.
New providers
We've added two new providers:
Shopify (#1890) - for Shopify store images
export default defineNuxtConfig({
image: {
provider: 'shopify',
shopify: {
baseURL: 'https://your-store.myshopify.com'
}
}
})Performance
We've made several optimizations to reduce bundle size and improve runtime performance:
Better URL encoding (#1813) - Switched to
URLSearchParamsfor more reliable parameter handlingReduced runtime utilities (#1816) - Removed unused code and simplified implementations
Streamlined screen sizes (#1931) - Aligned default breakpoints with Tailwind CSS
Better layer support
Nuxt Image now properly supports custom image directories within Nuxt layers (#1880), making it easier to organize images in modular projects.
Breaking changes
Provider API
The biggest breaking change is how providers are defined. All providers now use a default export 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. But you get 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. See the migration guide for details.
#### Screen sizes Default screen sizes now match Tailwind CSS. We've removed `xs` (320px) and `xxl` (2560px). See the [migration guide](https://image.nuxt.com/get-started/migration#update-screen-sizes) for how to add them back if needed.
Removed utilities
We've removed several unused runtime utilities. If you were importing internal utilities directly, check if they still exist.
Upgrading
Check out our comprehensive migration guide for step-by-step upgrade instructions.
The quick version:
npm install @nuxt/image@latest
Most apps can upgrade with no code changes. If you have custom providers, you'll need to update them to use defineProvider - see the migration guide for examples.
Bug fixes
This release includes several fixes:
Preload links: Fixed preload for multiple densities with single size
Crossorigin attributes: Correct crossorigin on preload links
Provider-specific formats: AWS Amplify and Vercel providers now have proper format allow lists
Hygraph: Prevented broken image URLs
Preset sizes: Fixed preset size application when component sizes prop is undefined
Cloudflare: Don't add baseURL if there are no operations
IPX: Always use IPX provider if external baseURL is provided
Changelog
Enhancements
Add support for image helpers in nitro endpoints
deps: Upgrade to ipx v3
ipx: Log the architecture of the build
- Breaking
⚠️ Typed providers + modifiers
Add type for default nuxt-picture slots
nuxt-img: Add types for default slot
Add shopify provider
Add support for image helpers in nitro endpoints
ipx: Log the architecture of the build
cloudimage: Make baseURL optional with cdn
nuxt-img: Expose element
Support custom image dirs within layers
Strongly type $Img/useImage methods
Add type hints for provider option
Performance
nuxt-img: Call decode before swapping from placeholder
Fixes
Remove layer0 and edgio providers
Add back layer0 and edgio providers (without) tests
cloudflare: Don't add baseURL if there are no operations
ipx: Always use ipx provider if external baseURL is provided
ipxStatic: Strip repeated slashes from image path
edgio,layer0: ⚠️ Remove providers
- Breaking
⚠️ Use URLSearchParams as default formatter
nuxt-picture: Export DefaultSlotProps
aliyun: Explicitly import useRuntimeConfig
Remove layer0 and edgio providers
Add back layer0 and edgio providers (without) tests
cloudflare: Don't add baseURL if there are no operations
ipx: Always use ipx provider if external baseURL is provided
ipxStatic: Strip repeated slashes from image path
Avoid deep type instantiation
Add types to new node + shared contexts
nuxt-img: Correct preload link for multiple densities + single size
nuxt-img: Add appropriate crossorigin attribute to preload link
awsAmplify,vercel: Set allow list of formats for providers
hygraph: Prevent broken image urls
nuxt-img: Apply preset sizes when component sizes prop is undefined
Refactors
- Breaking
⚠️ Remove unused runtime utilities and simplify code
- Breaking
⚠️ Remove xs and xxl screen sizes
CI
Breaking Changes
- Breaking
⚠️ Typed providers + modifiers
- Breaking
edgio,layer0: ⚠️ Remove providers
- Breaking
⚠️ Use URLSearchParams as default formatter
- Breaking
⚠️ Remove unused runtime utilities and simplify code
- Breaking
⚠️ Remove xs and xxl screen sizes
A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.