Releases · nuxt/image

05 Nov 10:38

Immutable

v2.0.0

27f9989

v2.0.0 Latest

Latest

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:

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

<script setup>
const imgEl = ref()

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

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
GitHub (#1990) - for GitHub avatars and user content

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 URLSearchParams for more reliable parameter handling
Reduced 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/getting-started/migration#screen-size-changes) 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 (#1851)
Crossorigin attributes: Correct 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: Don't add baseURL if there are no operations (#1790)
IPX: Always use IPX provider if external baseURL is provided (#1800)

🙏 Thank you

Thank you to all the contributors who made this release possible! This includes contributions from dozens of community members who helped with features, bug fixes, documentation improvements, and feedback.

👉 Changelog

compare changes

🚀 Enhancements

Add support for image helpers in nitro endpoints (#1473)
deps: Upgrade to ipx v3 (#1799)
ipx: Log the architecture of the build (#1808)
⚠️ Typed providers + modifiers (#1802)
Add type for default nuxt-picture slots (0e4f174)
nuxt-img: Add types for default slot (c4bba1b)
Add shopify provider (#1890)
Add support for image helpers in nitro endpoints (#1473)
ipx: Log the architecture of the build (#1808)
cloudimage: Make baseURL optional with cdn (#1951)
github: Add provider for github avatars (#1990)
nuxt-img: Expose element (#1834)
Support custom image dirs within layers (#1880)
Strongly type $Img/useImage methods (#1844)
Add type hints for provider option (64c76ee)

🔥 Performance

nuxt-img: Call decode before swapping from placeholder (#2008)

🩹 Fixes

Remove layer0 and edgio providers (#1763)
Add back layer0 and edgio providers (without) tests (fee826c)
cloudflare: Don't add baseURL if there are no operations (#1790)
ipx: Always use ipx provider if external baseURL is provided (#1800)
ipxStatic: Strip repeated slashes from image path (#1801)
edgio,layer0: ⚠️ Remove providers (#1809)
⚠️ Use URLSearchParams as default formatter (#1813)
nuxt-picture: Export DefaultSlotProps (891d79a)
aliyun: Explicitly import useRuntimeConfig (268eb9c)
Remove layer0 and edgio providers (#1763)
Add back layer0 and edgio providers (without) tests (a99ce09)
cloudflare: Don't add baseURL if there are no operations (#1790)
ipx: Always use ipx provider if external baseURL is provided (#1800)
ipxStatic: Strip repeated slashes from image path ([#1801](https://github.com/nuxt/image/pul...

Contributors

aaharu, screeny05, and 22 other contributors

Assets 3

30 Jul 09:22

danielroe

v1.11.0

3123997

v1.11.0

compare changes

🚀 Enhancements

Add support for image helpers in nitro endpoints (#1473)
ipx: Log the architecture of the build (#1808)

🩹 Fixes

Remove layer0 and edgio providers (#1763)
Add back layer0 and edgio providers (without) tests (a99ce09)
cloudflare: Don't add baseURL if there are no operations (#1790)
ipx: Always use ipx provider if external baseURL is provided (#1800)
ipxStatic: Strip repeated slashes from image path (#1801)
Avoid deep type instantiation (12b37a2)

📖 Documentation

Fix typo (#1762)
Fix link to runtime/providers (#1819)

🏡 Chore

Disable shamefully-hoist (#1795)
Do not ignore typescript upgrades (0809991)
Switch to using typesVersions field (b4af05a)
Allow major bumps in changelog (d486587)
Enable oxc-resolver build (4be31c7)
Release v1.11.0 (3123997)

✅ Tests

Exclude layer0 + edgio from unit tests (3682a90)

🤖 CI

Run tests against 1.x branch (0c83646)
Add release workflow and add pkg.pr.new (#1791)
Set fetch-depth (18ae6c7)
Test vs node 20 (e6babef)

❤️ Contributors

Daniel Roe (@danielroe)
Matis (@matisbag)
Amir Afshar (@Afshar07)
Sébastien Chopin (@atinux)
Nicolas Großmann (@grossmann94)

Contributors

atinux, danielroe, and 3 other contributors

Assets 2

05 May 10:08

danielroe

v2.0.0-alpha.1

f3bd1a3

v2.0.0-alpha.1 Pre-release

Pre-release

This is an alpha version of Nuxt Image v2

👀 Highlights

We'd love your feedback! This release contains quite a lot of changes, including (of course) breaking changes. It also brings a great deal of type safety, though we need to (and plan to!) improve the modifier types for each provider before release.