vue-image-kit — полный toolkit для изображений во Vue 3

npm install vue-image-kit

// main.ts
import { createApp } from 'vue'
import { VImageKitPlugin } from 'vue-image-kit'
import App from './App.vue'

const app = createApp(App)

app.use(VImageKitPlugin, {
  breakpoints: {           // глобальные брейкпоинты для art direction
    sm: '(max-width: 640px)',
    md: '(max-width: 1024px)',
    lg: '(min-width: 1025px)',
  },
})

app.mount('#app')

<VImage src="/photo.jpg" alt="Фото" />

<VImage
  src="/photo.jpg"              <!-- URL или объект { avif, webp, fallback } -->
  alt="Описание"                <!-- обязательный alt-текст -->
  :width="1200"                 <!-- резервирует место, предотвращает layout shift -->
  :height="800"

  thumbhash="3OcRJYB4d3h/..."  <!-- ThumbHash: декодируется в PNG-плейсхолдер -->
  blurhash="LEHV6nWB2yk8..."   <!-- BlurHash: рисуется на <canvas> -->
  placeholder="data:image/..."  <!-- LQIP base64: blur-up плейсхолдер -->
  placeholder-mode="blur"       <!-- 'blur' | 'color' | 'shimmer' -->
  placeholder-color="#1e3a8a"   <!-- явный сплошной цвет-плейсхолдер -->

  :widths="[400, 800, 1200]"   <!-- генерирует srcset-дескрипторы ширин -->
  :densities="[1, 2, 3]"        <!-- density-дескрипторы 1x/2x/3x (или { 1: …, 2: … } — разные файлы) -->
  sizes="(max-width: 768px) 100vw, 50vw"  <!-- подсказка браузеру какой размер выбрать -->
  :breakpoints="{ xs: '(max-width: 375px)' }"  <!-- локальные брейкпоинты (мёрджатся с глобальными) -->
  :sources="{ sm: '/photo-mobile.jpg', md: '/photo-tablet.jpg' }"  <!-- разные кадры для разных экранов -->

  :lazy="true"                  <!-- ленивая загрузка через IntersectionObserver -->
  root-margin="300px"           <!-- начать загрузку за 300px до вхождения в viewport -->
  :threshold="0"                <!-- доля видимости для срабатывания IO -->

  fit="cover"                   <!-- object-fit на <img> -->
  :focal="{ x: 0.5, y: 0.3 }"   <!-- точка фокуса при fit=cover → object-position -->
  fetchpriority="high"          <!-- приоритет загрузки (high для LCP-изображений) -->
  decoding="async"              <!-- не блокировать основной поток при декодировании -->

  :max-retries="3"              <!-- повторить загрузку N раз при ошибке -->
  :retry-delay="500"            <!-- начальная задержка перед retry в мс (x2 каждый раз) -->

  @load="onLoad"                <!-- событие при успешной загрузке -->
  @error="onError"              <!-- событие при ошибке (после всех retry) -->
>
  <template #error>             <!-- кастомный UI при неудаче вместо серого прямоугольника -->
    <div class="fallback">Не удалось загрузить</div>
  </template>
</VImage>

<VImage
  src="/photo.jpg"
  alt="Фото"
  thumbhash="1+cNHYI3iHeFh3iPh5d4h7ZwZQl4"
  :width="1200"
  :height="800"
/>

import { decodeThumbHash } from 'vue-image-kit'

const dataUrl = decodeThumbHash('1+cNHYI3iHeFh3iPh5d4h7ZwZQl4')
// → 'data:image/png;base64,...'

// Можно использовать как src для обычного <img>
// или как background-image — например с v-lazy-img

<VImage
  src="/photo.jpg"
  alt="Пейзаж"
  blurhash="LEHV6nWB2yk8pyo0adR*.7kCMdnj"
  :width="1200"
  :height="800"
/>

import { decodeBlurhash } from 'vue-image-kit'

const pixels = decodeBlurhash('LEHV6nWB2yk8pyo0adR*.7kCMdnj', 32, 32)
// pixels: Uint8ClampedArray — RGBA, row-major

const canvas = document.createElement('canvas')
canvas.width = 32
canvas.height = 32
canvas.getContext('2d')!.putImageData(new ImageData(pixels, 32, 32), 0, 0)

<VImage
  src="/photo.jpg"
  alt="Фото"
  placeholder="data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAA..."
  :width="1200"
  :height="800"
/>

import sharp from 'sharp'

const buffer = await sharp('photo.jpg')
  .resize(20)
  .jpeg({ quality: 20 })
  .toBuffer()

const lqip = `data:image/jpeg;base64,${buffer.toString('base64')}`

<VImage
  src="/photo.jpg"
  alt="Фото"
  :width="1200"
  :height="800"
  thumbhash="3OcRJYB4d3h/iIeHeEh3eIhw+j5n"
  placeholder-mode="color"
/>

<VImage src="/photo.jpg" alt="Баннер" placeholder-color="#1e3a8a" />

import { thumbHashToAverageRGBA, thumbHashToAverageColor } from 'vue-image-kit'

thumbHashToAverageRGBA('3OcRJYB4d3h/iIeHeEh3eIhw+j5n')
// → { r, g, b, a }  (каждый канал 0–1)

thumbHashToAverageColor('3OcRJYB4d3h/iIeHeEh3eIhw+j5n')
// → 'rgba(150, 146, 104, 1.000)'  — сразу в background-color

<VImage src="/photo.jpg" alt="Карточка" :width="400" :height="300" placeholder-mode="shimmer" />

import { encodeThumbHash, encodeBlurhash, decodeThumbHash } from 'vue-image-kit'

async function onFileSelected(file: File) {
  const thumbhash = await encodeThumbHash(file)
  // → base64-строка; сразу в <VImage :thumbhash="thumbhash">
  //   или decodeThumbHash(thumbhash) для превью

  const blurhash = await encodeBlurhash(file, { componentX: 4, componentY: 3 })
}

<script setup lang="ts">
import { ref } from 'vue'
import { encodeThumbHash } from 'vue-image-kit'

const hash = ref('')
const previewUrl = ref('')

async function handleUpload(e: Event) {
  const file = (e.target as HTMLInputElement).files?.[0]
  if (!file) return
  previewUrl.value = URL.createObjectURL(file)
  hash.value = await encodeThumbHash(file)   // считается за миллисекунды
  // hash отправляем на сервер вместе с файлом — больше его считать не нужно
}
</script>

<template>
  <input type="file" accept="image/*" @change="handleUpload" />
  <VImage v-if="hash" :src="previewUrl" alt="Превью" :thumbhash="hash" />
</template>

// images.ts — сгенерировано CLI
{
  src:    '/images/photo.jpg',
  srcset: '/images/photo-400.jpg 400w, /images/photo-800.jpg 800w, /images/photo.jpg 1200w',
  // ...
}

<VImage
  :src="img.src"
  :alt="img.name"
  :srcset="img.srcset"
  sizes="(max-width: 768px) 100vw, 50vw"
/>

<script setup lang="ts">
import { imgix } from 'vue-image-kit/cdn'

const cdn = imgix('https://mysite.imgix.net')
</script>

<template>
  <VImage
    :src="cdn.url('/photo.jpg', { width: 1200 })"
    :alt="'Фото'"
    :srcset="cdn.srcset('/photo.jpg', [400, 800, 1200])"
    sizes="(max-width: 768px) 100vw, 50vw"
  />
  <!--
    srcset:
      https://mysite.imgix.net/photo.jpg?w=400&auto=format 400w,
      https://mysite.imgix.net/photo.jpg?w=800&auto=format 800w,
      https://mysite.imgix.net/photo.jpg?w=1200&auto=format 1200w
  -->
</template>

import { buildSizes } from 'vue-image-kit'

const breakpoints = {
  sm: '(max-width: 640px)',
  md: '(max-width: 1024px)',
}

buildSizes({ sm: '100vw', md: '50vw', default: '33vw' }, breakpoints)
// → '(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw'

<VImage
  src="/avatar.png"
  alt="Аватар"
  :width="64"
  :height="64"
  :densities="{ 1: '/avatar.png', 2: '/avatar@2x.png', 3: '/avatar@3x.png' }"
/>
<!-- → srcset="/avatar.png 1x, /avatar@2x.png 2x, /avatar@3x.png 3x" -->

<VImage src="https://cdn.example.com/avatar?dpr=auto" alt="Аватар" :densities="[1, 2, 3]" />

import { generateDensitySrcset } from 'vue-image-kit'

generateDensitySrcset({ 1: '/a.png', 2: '/a@2x.png' }, [1, 2])
// → '/a.png 1x, /a@2x.png 2x'

<!-- { x: 0.5, y: 0.3 } — верхняя середина: типично для портретов -->
<VImage
  src="/portrait.jpg"
  alt="Сотрудник"
  :width="400"
  :height="400"
  fit="cover"
  :focal="{ x: 0.5, y: 0.3 }"
/>

<VImage
  :src="{
    avif: '/photo.avif',
    webp:  '/photo.webp',
    fallback: '/photo.jpg',
  }"
  alt="Фото"
  :width="1200"
  :height="800"
/>

<picture>
  <source srcset="/photo.avif" type="image/avif" />
  <source srcset="/photo.webp" type="image/webp" />
  <img src="/photo.jpg" alt="Фото" width="1200" height="800" />
</picture>

// main.ts — один раз глобально
app.use(VImageKitPlugin, {
  breakpoints: {
    sm: '(max-width: 640px)',
    md: '(max-width: 1024px)',
  },
})

<!-- В компоненте — только ключи -->
<VImage
  src="/hero-desktop.jpg"
  alt="Hero"
  :sources="{
    sm: '/hero-mobile.jpg',
    md: '/hero-tablet.jpg',
  }"
/>

<VImage
  src="/product-desktop.jpg"
  alt="Продукт"
  :breakpoints="{
    xs:   '(max-width: 375px)',
    wide: '(min-width: 1600px)',
  }"
  :sources="{
    xs:   '/product-xs.jpg',
    sm:   '/product-mobile.jpg',
    md:   '/product-tablet.jpg',
    wide: '/product-wide.jpg',
  }"
/>

<VImage
  :src="{ avif: '/hero.avif', webp: '/hero.webp', fallback: '/hero.jpg' }"
  :sources="{ sm: '/hero-mobile.jpg', md: '/hero-tablet.jpg' }"
  alt="Hero"
/>

<picture>
  <source media="(max-width: 640px)"  srcset="/hero-mobile.jpg" />
  <source media="(max-width: 1024px)" srcset="/hero-tablet.jpg" />
  <source srcset="/hero.avif" type="image/avif" />
  <source srcset="/hero.webp" type="image/webp" />
  <img src="/hero.jpg" alt="Hero" />
</picture>

<!-- Дефолт: начать загрузку за 200px до вхождения в viewport -->
<VImage src="/photo.jpg" alt="Фото" />

<!-- Начать за 500px — изображения успеют загрузиться к скроллу -->
<VImage src="/photo.jpg" alt="Фото" root-margin="500px" />

<!-- Загружать только когда 50% изображения в viewport -->
<VImage src="/photo.jpg" alt="Фото" :threshold="0.5" />

<!-- Отключить lazy — загрузить сразу (above the fold) -->
<VImage src="/hero.jpg" alt="Hero" :lazy="false" />

<VImage src="/missing.jpg" alt="Фото" :width="400" :height="300">
  <template #error>
    <div class="error-placeholder">
      <img src="/no-image.svg" alt="" />
      <p>Изображение недоступно</p>
    </div>
  </template>
</VImage>

<script setup lang="ts">
function handleError(e: Event) {
  analytics.track('image_load_failed', { src: currentSrc })
}
</script>

<template>
  <VImage src="/photo.jpg" alt="Фото" @error="handleError" />
</template>

<!-- 3 попытки: 500ms → 1000ms → 2000ms -->
<VImage
  src="/flaky-cdn.jpg"
  alt="Фото"
  :max-retries="3"
  :retry-delay="500"
/>

<!-- Hero-изображение: загружать первым, не блокировать рендер -->
<VImage
  src="/hero.jpg"
  alt="Hero"
  :lazy="false"
  fetchpriority="high"
  decoding="async"
/>

<!-- Изображения в подвале: минимальный приоритет -->
<VImage
  src="/footer-banner.jpg"
  alt="Баннер"
  fetchpriority="low"
/>

<!-- Простая строка — только src -->
<div v-lazy-img="'/background.jpg'" class="hero" />

<!-- Объект с плейсхолдером и колбеками -->
<div
  v-lazy-img="{
    src: '/background.jpg',
    placeholder: 'data:image/jpeg;base64,...',
    rootMargin: '100px',
    onLoad: () => console.log('loaded'),
    onError: (e) => console.error('failed', e),
  }"
  class="hero"
/>

import type { LazyImgOptions } from 'vue-image-kit'

const bgOptions: LazyImgOptions = {
  src: '/hero.jpg',
  placeholder: 'data:image/jpeg;base64,...',
  rootMargin: '150px',
  onLoad: () => analytics.track('hero_loaded'),
  onError: (e) => logger.error('hero_failed', e),
}

<div v-lazy-img="bgOptions" class="hero-section" />

<script setup lang="ts">
import { useBackgroundImage } from 'vue-image-kit'

const { target, style, isLoaded } = useBackgroundImage('/hero.jpg', {
  placeholder: 'data:image/jpeg;base64,/9j/...',  // блюрится, пока грузится оригинал
  densities: [1, 2],                               // → image-set(url(...) 1x, url(...) 2x)
  rootMargin: '300px',
})
</script>

<template>
  <section ref="target" :style="style" class="hero">
    <h1 v-show="isLoaded">Заголовок</h1>
  </section>
</template>

<style scoped>
.hero { width: 100%; height: 60vh; }
</style>

const {
  status,       // Ref<'idle' | 'loading' | 'loaded' | 'error'>
  isLoaded,     // ComputedRef<boolean>
  isError,      // ComputedRef<boolean>
  imgAttrs,     // ComputedRef<{ src, srcset?, sizes?, style }> — v-bind на <img>
  observe,      // (el: Ref<HTMLElement | null>) => void
  onImgLoad,    // () => void — вызвать из @load
  onImgError,   // () => void — вызвать из @error
} = useImage({
  src: '/photo.jpg',
  widths: [400, 800, 1200],
  sizes: '(max-width: 768px) 100vw, 50vw',
  lazy: true,
  rootMargin: '200px',
  maxRetries: 3,
  retryDelay: 500,
})

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { useImage } from 'vue-image-kit'

const containerRef = ref<HTMLElement | null>(null)

const { status, isLoaded, isError, imgAttrs, observe, onImgLoad, onImgError } = useImage({
  src: '/photo.jpg',
  widths: [400, 800, 1200],
  sizes: '(max-width: 768px) 100vw, 50vw',
})

onMounted(() => observe(containerRef))
</script>

<template>
  <div ref="containerRef" class="image-wrapper">
    <!-- Skeleton пока idle -->
    <div v-if="status === 'idle'" class="skeleton" />

    <!-- Изображение появляется с transition -->
    <img
      v-if="status === 'loading' || isLoaded"
      v-bind="imgAttrs"
      alt="Фото"
      :class="{ 'is-visible': isLoaded }"
      @load="onImgLoad"
      @error="onImgError"
    />

    <!-- Кастомный error state -->
    <div v-if="isError" class="error-state">
      <IconBrokenImage />
      <button @click="retry">Повторить</button>
    </div>
  </div>
</template>

<style scoped>
img { opacity: 0; transition: opacity 0.4s ease; }
img.is-visible { opacity: 1; }
</style>

<script setup lang="ts">
import { useImagePreloader } from 'vue-image-kit'

const { preload, progress, isComplete, errors } = useImagePreloader()

// При hover на следующий слайд — начинаем грузить заранее
async function onNextHover() {
  await preload(['/slide-2.jpg', '/slide-3.jpg', '/slide-4.jpg'])
  // Все изображения закешированы — переход мгновенный
}
</script>

<template>
  <div class="slider">
    <!-- Прогресс предзагрузки -->
    <div v-if="!isComplete" class="preload-progress">
      Загрузка {{ Math.round(progress * 100) }}%
    </div>

    <button
      @click="goNext"
      @mouseover="onNextHover"
    >
      Следующий →
    </button>
  </div>
</template>

import { generatePreloadLink, generateSrcset } from 'vue-image-kit'

const srcset = generateSrcset('/hero.jpg', [640, 1024, 1920])

const linkTag = generatePreloadLink('/hero.jpg', {
  srcset,
  sizes: '100vw',
})
// → '<link rel="preload" as="image" href="/hero.jpg" imagesrcset="..." imagesizes="100vw">'

<script setup lang="ts">
import { generatePreloadLink } from 'vue-image-kit'

useHead({
  link: [{
    innerHTML: generatePreloadLink('/hero.jpg', {
      srcset: generateSrcset('/hero.jpg', [640, 1024, 1920]),
      sizes: '100vw',
    }),
  }],
})
</script>

import {
  cloudinary, imgix, bunny, sanity, storyblok, contentful, vercel,
  cloudflare, imagekit, twicpics, netlify, gumlet,
} from 'vue-image-kit/cdn'

const cdn = cloudinary({ cloudName: 'my-cloud' })

cdn.url('photo.jpg', { width: 800, format: 'webp', quality: 'auto' })
// → https://res.cloudinary.com/my-cloud/w_800,q_auto,f_webp/image/upload/photo.jpg

cdn.srcset('photo.jpg', [400, 800, 1200])
// → 'https://...w_400,... 400w, https://...w_800,... 800w, ...'

const cdn = imgix('https://mysite.imgix.net')

cdn.url('photo.jpg', { width: 800, dpr: 2 })
// → https://mysite.imgix.net/photo.jpg?w=800&dpr=2&auto=format

cdn.srcset('photo.jpg', [400, 800, 1200])

const cdn = bunny('https://myzone.b-cdn.net')
cdn.url('photo.jpg', { width: 800, height: 600, format: 'webp', quality: 85 })

const cdn = sanity({ projectId: 'abc123', dataset: 'production' })
cdn.url('image-abc123-800x600-jpg', { width: 400 })

const cdn = storyblok()
cdn.url('https://a.storyblok.com/f/12345/photo.jpg', { width: 800 })

const cdn = contentful()
cdn.url('https://images.ctfassets.net/space/token/photo.jpg', { width: 800, format: 'webp' })

const cdn = vercel({ origin: 'https://myapp.vercel.app' })
cdn.url('/photo.jpg', { width: 800, quality: 75 })
// → https://myapp.vercel.app/_vercel/image?url=%2Fphoto.jpg&w=800&q=75

const cdn = cloudflare('https://example.com')
cdn.url('/photo.jpg', { width: 800, format: 'webp' })
// → https://example.com/cdn-cgi/image/width=800,format=webp/photo.jpg

const cdn = imagekit('https://ik.imagekit.io/your_id')
cdn.url('photo.jpg', { width: 800, format: 'webp' })
// → https://ik.imagekit.io/your_id/photo.jpg?tr=w-800,f-webp

const cdn = twicpics('https://demo.twic.pics')
cdn.url('photo.jpg', { width: 800, format: 'webp' })
// → https://demo.twic.pics/photo.jpg?twic=v1/resize=800/output=webp

const cdn = netlify({ origin: 'https://myapp.netlify.app' })
cdn.url('/photo.jpg', { width: 800, format: 'webp', quality: 75 })
// → https://myapp.netlify.app/.netlify/images?url=%2Fphoto.jpg&w=800&fm=webp&q=75

const cdn = gumlet('https://demo.gumlet.io')
cdn.url('photo.jpg', { width: 800, format: 'webp' })
// → https://demo.gumlet.io/photo.jpg?w=800&format=webp

<script setup lang="ts">
import { cloudinary } from 'vue-image-kit/cdn'

const cdn = cloudinary({ cloudName: 'my-cloud' })
</script>

<template>
  <VImage
    src="/photo.jpg"
    alt="Фото"
    :srcset="cdn.srcset('/photo.jpg', [400, 800, 1200])"
    sizes="(max-width: 768px) 100vw, 50vw"
  />
</template>

npm install sharp --save-dev          # sharp — единственная зависимость CLI
npm install thumbhash --save-dev     # для --thumbhash флага

npx vue-image-kit generate \
  --input   ./src/images \
  --output  ./public/images \
  --widths  400,800,1200 \
  --formats jpg,webp,avif \
  --quality '{"jpg":85,"webp":80,"avif":65}' \
  --lqip \
  --blurhash \
  --thumbhash \
  --manifest ./src/assets/images.ts \
  --public-path /images \
  --concurrency 8

// vue-image-kit.config.js
export default {
  input:      './photos',
  output:     './public/images',
  widths:     [480, 960, 1440],
  formats:    ['jpg', 'webp', 'avif'],
  quality:    { jpg: 85, webp: 80, avif: 65 },
  manifest:   './src/assets/images.ts',
  publicPath: '/images',
  blurhash:   true,
  thumbhash:  true,
}

export interface ImageData {
  name:        string
  src:         string
  webp:        string
  avif:        string
  srcset:      string
  src400:      string
  src800:      string
  src1200:     string
  width:       number
  height:      number
  placeholder: string  // base64 LQIP
  blurhash:    string
  thumbhash:   string
}

export const images: ImageData[] = [
  {
    name:     'photo-1',
    src:      '/images/photo-1.jpg',
    webp:     '/images/photo-1.webp',
    avif:     '/images/photo-1.avif',
    srcset:   '/images/photo-1-400.jpg 400w, /images/photo-1-800.jpg 800w, /images/photo-1.jpg 1200w',
    width:    1200,
    height:   800,
    placeholder: 'data:image/jpeg;base64,/9j/...',
    blurhash: 'LRB|jIkEDhj[EAozngay?wo#Riof',
    thumbhash: '1+cNHYI3iHeFh3iPh5d4h7ZwZQl4',
    // ...
  },
]

// vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { vueImageKit } from 'vue-image-kit/vite'

export default defineConfig({
  plugins: [
    vue(),
    vueImageKit({
      input:      './src/images',
      output:     './public/images',
      widths:     [400, 800, 1200],
      formats:    ['jpg', 'webp', 'avif'],
      manifest:   './src/assets/images.ts',
      blurhash:   true,
      thumbhash:  true,
    }),
  ],
})

import meta from './photo.jpg?vik'
// → { src, srcset, webp, avif, width, height, placeholder, blurhash, thumbhash, name, src400, … }

import hash from './photo.jpg?thumbhash'
// → 'base64string'

<script setup lang="ts">
import meta from './hero.jpg?vik'
</script>

<template>
  <VImage
    :src="meta.src"
    :srcset="meta.srcset"
    :width="meta.width"
    :height="meta.height"
    :thumbhash="meta.thumbhash"
    alt="Hero"
  />
</template>

/// <reference types="vue-image-kit/vite/client" />

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['vue-image-kit/nuxt'],

  vueImageKit: {
    breakpoints: {
      sm: '(max-width: 640px)',
      md: '(max-width: 1024px)',
    },
  },
})

import type {
  ImageStatus,      // 'idle' | 'loading' | 'loaded' | 'error'
  SrcSet,           // { avif?: string; webp?: string; fallback: string }
  ResponsiveSrc,    // Record<string, string> — брейкпоинт → URL
  BreakpointMap,    // Record<string, string> — брейкпоинт → media query
  VImageKitOptions, // { breakpoints?: BreakpointMap }
  LazyImgOptions,   // { src, placeholder?, rootMargin?, threshold?, onLoad?, onError? }
  ObjectFit,        // 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'
  FocalPoint,       // { x: number; y: number } — доли 0–1
  Densities,        // number[] | Record<number, string>
} from 'vue-image-kit'

// Только vLazyImg и его IO-логика попадают в бандл
import { vLazyImg } from 'vue-image-kit'
app.directive('lazy-img', vLazyImg)

// src/cdn.ts — конфигурация провайдера в одном месте
import { cloudinary } from 'vue-image-kit/cdn'

const _cdn = cloudinary({ cloudName: 'myshop' })

export const cdn = {
  product(publicId: string) {
    return {
      fallback: _cdn.url(publicId, { width: 800, format: 'jpg', quality: 85 }),
      webp:     _cdn.url(publicId, { width: 800, format: 'webp', quality: 80 }),
      avif:     _cdn.url(publicId, { width: 800, format: 'avif', quality: 65 }),
    }
  },

  productSrcset(publicId: string) {
    return _cdn.srcset(publicId, [400, 800, 1200])
  },

  thumb(publicId: string) {
    return _cdn.url(publicId, { width: 20, format: 'jpg', quality: 20 })
  },
}

<!-- ProductCard.vue -->
<script setup lang="ts">
import { cdn } from '@/cdn'

const props = defineProps<{
  product: {
    id:        string
    name:      string
    imageId:   string | null
    thumbhash: string | null
  }
}>()
</script>

<template>
  <article class="product-card">
    <VImage
      v-if="product.imageId"
      :src="cdn.product(product.imageId)"
      :alt="product.name"
      :width="800"
      :height="800"
      :thumbhash="product.thumbhash ?? undefined"
      :widths="[400, 800]"
      sizes="(max-width: 640px) 50vw, (max-width: 1024px) 33vw, 25vw"
      fit="contain"
      :max-retries="3"
      :retry-delay="800"
    >
      <template #error>
        <div class="no-photo">
          <IconPhoto class="no-photo__icon" />
          <span>Фото не найдено</span>
        </div>
      </template>
    </VImage>

    <!-- Товар без изображения -->
    <div v-else class="no-photo">
      <IconPhoto class="no-photo__icon" />
    </div>

    <h3 class="product-card__name">{{ product.name }}</h3>
  </article>
</template>

<!-- pages/gallery/[slug].vue -->
<script setup lang="ts">
import { generatePreloadLink, generateSrcset, useImagePreloader } from 'vue-image-kit'
import { images } from '@/assets/images'

const { slug } = useRoute().params
const gallery  = images.filter(img => img.category === slug)
const hero     = gallery[0]

const { preload } = useImagePreloader()

// Preload hint для первого изображения — браузер загрузит ещё до парсинга body
useHead({
  link: [{
    innerHTML: generatePreloadLink(hero.src, {
      srcset: hero.srcset,
      sizes:  '100vw',
    }),
  }],
})

// При hover на миниатюру — предзагрузить полный размер
async function onThumbHover(img: typeof hero) {
  await preload([img.src])
}
</script>

<template>
  <section class="gallery">
    <!-- Первый снимок — высокий приоритет, без lazy -->
    <VImage
      :src="{ avif: hero.avif, webp: hero.webp, fallback: hero.src }"
      :alt="hero.name"
      :width="hero.width"
      :height="hero.height"
      :thumbhash="hero.thumbhash"
      :widths="[640, 1024, 1920]"
      sizes="100vw"
      :lazy="false"
      fetchpriority="high"
      decoding="async"
      class="gallery__hero"
    />

    <!-- Остальные — ленивая загрузка с предзагрузкой -->
    <div class="gallery__grid">
      <div
        v-for="img in gallery.slice(1)"
        :key="img.name"
        class="gallery__thumb"
        @mouseover="onThumbHover(img)"
      >
        <VImage
          :src="{ avif: img.avif, webp: img.webp, fallback: img.src }"
          :alt="img.name"
          :width="img.width"
          :height="img.height"
          :thumbhash="img.thumbhash"
          :widths="[400, 800]"
          sizes="(max-width: 640px) 50vw, 33vw"
          root-margin="400px"
          class="gallery__thumb-image"
        />
      </div>
    </div>
  </section>
</template>

// src/cdn.ts
import { bunny } from 'vue-image-kit/cdn'

const _bunny = bunny('https://myapp.b-cdn.net')

export const cdn = {
  avatar:  (path: string, size: number) =>
    _bunny.url(path, { width: size, height: size, format: 'webp' }),

  banner:  (path: string) =>
    _bunny.url(path, { width: 1200, format: 'webp', quality: 80 }),

  attachment: (path: string, w: number) =>
    _bunny.url(path, { width: w, format: 'webp', quality: 85 }),

  attachmentSrcset: (path: string) =>
    _bunny.srcset(path, [400, 800, 1200]),
}

<!-- UserAvatar.vue -->
<template>
  <VImage
    :src="cdn.avatar(user.avatarPath, size)"
    :alt="user.displayName"
    :width="size"
    :height="size"
    :thumbhash="user.avatarThumbhash"
    :lazy="false"
    fetchpriority="high"
    fit="cover"
    class="avatar"
  />
</template>

<!-- SectionCard.vue -->
<script setup lang="ts">
import type { LazyImgOptions } from 'vue-image-kit'
import { cdn } from '@/cdn'

const props = defineProps<{
  section: { title: string; bannerPath: string; bannerLqip: string }
}>()

const bgOptions = computed<LazyImgOptions>(() => ({
  src: cdn.banner(props.section.bannerPath),
  placeholder: props.section.bannerLqip,
  rootMargin: '200px',
  onLoad: () => emit('banner-loaded'),
}))

const emit = defineEmits<{ 'banner-loaded': [] }>()
</script>

<template>
  <div
    v-lazy-img="bgOptions"
    class="section-card"
  >
    <div class="section-card__overlay">
      <h2>{{ section.title }}</h2>
    </div>
  </div>
</template>

<style scoped>
.section-card {
  aspect-ratio: 16/9;
  border-radius: 12px;
  background-size: cover;
  background-position: center;
}
</style>

<!-- TaskAttachment.vue -->
<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { useImage } from 'vue-image-kit'
import { cdn } from '@/cdn'

const props = defineProps<{
  attachment: { path: string; width: number; height: number; thumbhash: string }
}>()

const containerRef = ref<HTMLElement | null>(null)

const { status, isLoaded, isError, imgAttrs, observe, onImgLoad, onImgError } = useImage({
  src: cdn.attachment(props.attachment.path, 800),
  widths: [400, 800, 1200],
  sizes: '(max-width: 768px) 100vw, 600px',
  maxRetries: 2,
})

onMounted(() => observe(containerRef))
</script>

<template>
  <div ref="containerRef" class="attachment">
    <!-- ThumbHash пока idle и loading -->
    <img
      v-if="!isLoaded && !isError"
      :src="decodeThumbHash(attachment.thumbhash)"
      alt=""
      aria-hidden="true"
      class="attachment__placeholder"
    />

    <!-- Основное изображение -->
    <img
      v-if="status === 'loading' || isLoaded"
      v-bind="imgAttrs"
      :alt="`Вложение`"
      :class="['attachment__img', { 'attachment__img--loaded': isLoaded }]"
      @load="onImgLoad"
      @error="onImgError"
    />

    <!-- Error state с retry -->
    <button v-if="isError" class="attachment__retry" @click="() => status = 'idle'">
      Попробовать снова
    </button>
  </div>
</template>

<style scoped>
.attachment__placeholder {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
  object-fit: cover;
  filter: blur(12px);
  transform: scale(1.05);
}

.attachment__img {
  opacity: 0;
  transition: opacity 0.5s cubic-bezier(0.4, 0, 0.2, 1);
}

.attachment__img--loaded {
  opacity: 1;
}
</style>

git clone https://github.com/macrulezru/vue-image-kit.git
cd vue-image-kit
npm run demo