Image Kit

npm install @macrulez/vue-image-kit@latest

01 — Назначение

Когда это пригодится

Изображение почти всегда самый тяжёлый элемент на странице — и почти всегда именно оно определяет LCP, метрику, по которой Google и реальные пользователи оценивают скорость загрузки. vue-image-kit берёт на себя весь набор техник, которые обычно применяют вручную одну за другой: правильный формат, ленивую загрузку, плейсхолдеры, приоритет для самого важного изображения.

Главная картинка на экране не должна ждать своей очереди

Баннер или фото товара, которые видны сразу при открытии страницы, получают приоритет и начинают грузиться раньше остальных изображений — иначе именно они, а не мелкие иконки внизу, определят, насколько быстрой покажется страница.

Картинки ниже экрана не должны грузиться зря

Лента из полусотни фотографий не тянет все пятьдесят файлов сразу при открытии страницы — далёкие от экрана изображения начинают загружаться, только когда пользователь долистал почти до них.

Картинки хранятся в CDN, а не в папке проекта

Один проект держит изображения в Cloudinary, другой — в собственном облаке, и каждый сервис строит адрес нужного размера и формата по-своему — этот адрес собирается автоматически по правилам конкретного провайдера, а не вручную для каждого.

Пока фото ещё грузится, на его месте не должно быть пустоты

Пустой прямоугольник, который вдруг становится картинкой, дёргает страницу и выглядит небрежно — на месте ещё не загруженного изображения сразу показывается его размытая или цветная версия, подготовленная заранее.

02 — Фичи

Коротко о главном

Мощный компонент VImage с оптимизациями

Один компонент заменяет целый набор утилит: ленивая загрузка через IntersectionObserver, плейсхолдеры (HazeHash, Blurhash, ThumbHash, LQIP, цвет, шиммер), автоматический srcset, WebP/AVIF, арт-дирекшн, ретраи с экспоненциальной задержкой и плавные CSS-переходы. Поддерживаются focal point, fetchpriority, decoding и приоритетный режим для LCP.

CLI, Vite плагин и Nuxt модуль

CLI обрабатывает изображения на этапе сборки: ресайз, конвертация в WebP/AVIF, генерация LQIP и HazeHash/BlurHash/ThumbHash, запись TypeScript-манифеста. Vite-плагин запускает обработку при сборке и в режиме разработки. Nuxt-модуль автоматически регистрирует компонент и все композаблы, интегрируясь с рантайм-конфигом.

CDN адаптеры и автоопределение

Готовые URL-билдеры для 12 провайдеров (Cloudinary, imgix, Bunny, Sanity, Storyblok, Contentful, Vercel, Cloudflare, ImageKit, TwicPics, Netlify, Gumlet) с единым интерфейсом .url() и .srcset(). Функция autoLoader() определяет CDN по хосту и применяет адаптер автоматически, а VImage с пропом cdn делает это прямо в шаблоне.

Гибкие композаблы и директивы

useImage даёт headless-управление состоянием загрузки и атрибутами для кастомной разметки. v-lazy-img загружает фоновые изображения при входе в область видимости с поддержкой плейсхолдеров. useBackgroundImage добавляет lazy + responsive через CSS image-set(). useImagePreloader предзагружает изображения до навигации.

Производительность и SSR-безопасность

Встроенные механизмы: приоритетная загрузка (fetchpriority), декодирование (decoding), Network Information API (saveData), предзагрузка через generatePreloadLink и useImagePreloader. Пул общих IntersectionObserver для экономии ресурсов. Все компоненты и утилиты безопасны для SSR — на сервере рендерится обычный <img>, а вся клиентская логика активируется после гидратации.

Self-hosted сервер и on-demand режим разработки

Не хотите зависеть от внешнего CDN? Разверните собственный сервер обработки изображений как отдельную точку входа пакета — с тем же API ресайза и конвертации форматов, что и у CLI. А в режиме разработки Vite-плагин обрабатывает изображения по требованию, при первом запросе, ускоряя холодный старт.

03 — Быстрый пример

Как это работает

Никакого дрожания layout — плейсхолдер из строки

Blurhash-строка декодируется в CSS-градиент за микросекунды — плейсхолдер есть ещё до того, как долетел первый байт изображения, а width/height сразу резервируют место под картинку.

App.vue
<template>
  <VImage
    src="/photo.jpg"
    alt="Mountain landscape"
    :width="1200"
    :height="600"
    blurhash="LEHV6nWB2yk8pyo0adR*.7kCMdnj"
  />
</template>

Разный кадр под разные экраны, а не просто размер

sources подставляет полностью другое изображение — другой кадр, другую композицию — по брейкпоинту. Это честный art direction через <picture>, а не растянутый ресайз одной картинки.

ArtDirection.vue
<template>
  <VImage
    src="/hero-desktop.jpg"
    alt="Hero"
    :sources="{
      sm: '/hero-mobile.jpg',
      md: '/hero-tablet.jpg',
    }"
  />
</template>

<!-- Generates a real <picture> with one <source media="..."> per
     breakpoint, sorted automatically, plus the fallback <img>. -->

Учитывает Save-Data — не тянет тяжёлое без спроса

respect-save-data сам понижает src до самого лёгкого варианта и снимает приоритетную загрузку, пока у посетителя включена экономия трафика — решает телефон пользователя, а не разработчик.

SaveData.vue
<template>
  <VImage
    src="/photo.jpg"
    alt="Photo"
    priority
    respect-save-data
    :densities="{ 1: '/photo.jpg', 2: '/photo@2x.jpg' }"
  />
</template>

<!-- While the visitor has Save-Data on: priority is neutralized (stays
     lazy instead of eager), and src downgrades to the lightest candidate
     it can find — the lowest density here, @1x instead of @2x. -->