Release· 5 ноября 2025 г.

Nuxt Image v2

Вышел Nuxt Image v2 — полная поддержка TypeScript, IPX v3 и новые провайдеры.

Daniel Roe

@danielroe.dev

Мы рады представить Nuxt Image v2! 🎉 В фокусе релиза — поддержка TypeScript, улучшение производительности и удобство разработки.

Nuxt Image v2 работает с Nuxt 3.1+. Для Nuxt 3.0.x потребуется обновление как минимум до 3.1.

🎯 Поддержка TypeScript

Главное изменение в v2 — полная поддержка TypeScript во всём модуле (#1802).

Типизированные композаблы

Хелпер $img и композабл useImage() полностью типизированы (#1844):

const img = useImage()

// Полный автокомплит для модификаторов
const url = img('/image.jpg', { 
  width: 300,
  height: 200,
  fit: 'cover' // TypeScript знает допустимые значения!
})

Типобезопасная конфигурация

Опции модуля теперь полностью типизированы. Провайдерам, которым нужен baseURL, он задаётся на уровне типов в nuxt.config.ts:

nuxt.config.ts

export default defineNuxtConfig({
  image: {
    provider: 'bunny',
    bunny: {
      baseURL: '...' // Ошибка TypeScript, если не указать!
    }
  }
})

Типизированные провайдеры

Для кастомных провайдеров изображений используйте новый defineProvider для типобезопасной конфигурации:

// 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 }) {
    // Полностью типизированные модификаторы
    // ...
    return { url }
  }
})

🚀 IPX v3

Модуль переведён на IPX v3 (#1799) для лучшей производительности и корректной работы бинарников sharp. Обновление включает автоматический подбор нужных бинарников sharp под вашу платформу деплоя.

🔌 Серверные утилиты

Хелперы изображений теперь можно использовать прямо в 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' 
    })
  }
})

🎨 Улучшения компонентов

Template refs

<NuxtImg> теперь отдаёт доступ к внутреннему элементу <img> через template refs:

<script setup>
const img = useTemplateRef('img')

onMounted(() => {
  // Прямой доступ к нативному img-элементу
  console.log(img.value.imgEl)
})
</script>

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

Типизированные слоты

У <NuxtImg> и <NuxtPicture> теперь корректно типизированы слоты по умолчанию.

<template>
  <NuxtImg src="/image.jpg" custom>
    <template #default="{ imgAttrs, isLoaded, src }">
      <img v-bind="imgAttrs" :src="src">
      <span v-if="!isLoaded">Загрузка...</span>
    </template>
  </NuxtImg>
</template>

В слоте доступны:

imgAttrs — все вычисляемые атрибуты изображения (sizes, srcset и т.д.)
isLoaded — загружен ли плейсхолдер
src — итоговый URL изображения

🌐 Новые провайдеры

Shopify

Доступна настройка провайдера Shopify (#1890):

nuxt.config.ts

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

GitHub

Провайдер для аватарок и контента пользователей GitHub (#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" />

⚡ Производительность

Сделаны оптимизации для уменьшения бандла и ускорения рантайма:

Кодирование URL (#1813) — переход на URLSearchParams для надёжной передачи параметров
Меньше рантайм-утилит (#1816) — удалён неиспользуемый код, упрощены реализации
Экраны по умолчанию (#1931) — брейкпоинты приведены к Tailwind CSS

🎯 Поддержка слоёв

Nuxt Image корректно поддерживает кастомные директории изображений в Nuxt layers (#1880) — удобнее организовывать картинки в модульных проектах.

⚠️ Breaking changes

API провайдеров

Главное изменение — способ объявления провайдеров. Все провайдеры используют default export с обёрткой defineProvider:

- export const getImage = (src, { modifiers }) => { ... }
+ export default defineProvider({
+   getImage(src, { modifiers }) { ... }
+ })

Кастомные провайдеры нужно обновить — зато вы получаете полную поддержку TypeScript.

Удалённые провайдеры

Устаревшие провайдеры layer0 и edgio удалены.

URL formatters

Провайдерам с joinWith для форматирования параметров нужно перейти на функцию formatter с createOperationsGenerator. Подробности — в руководстве по миграции.

Размеры экранов

Размеры по умолчанию приведены к Tailwind CSS. Удалены xs (320px) и xxl (2560px). Как вернуть их при необходимости — в руководстве по миграции.

Удалённые утилиты

Удалён ряд неиспользуемых рантайм-утилит. При прямом импорте внутренних утилит проверьте, что они ещё существуют.

✅ Обновление

Пошаговые инструкции — в руководстве по миграции.

Кратко:

Terminal

npm install @nuxt/image@latest

Большинству приложений достаточно обновить пакет. Кастомные провайдеры нужно перевести на defineProvider — примеры в руководстве по миграции.

🐛 Исправления

В релиз вошли исправления:

Preload links — исправлен preload для нескольких плотностей при одном размере (#1851)
Crossorigin — корректный crossorigin для preload-ссылок (#1836)
Форматы провайдеров — у AWS Amplify и Vercel заданы корректные allow list форматов (#1996)
Hygraph — исправлены битые URL изображений (#1999)
Preset sizes — корректное применение при неопределённом prop sizes (#1919)
Cloudflare — baseURL не добавляется при отсутствии операций (#1790)
IPX — при указании внешнего baseURL всегда используется провайдер IPX (#1800)

← Вернуться в блог