VueCraft NPM

CLI, CDN и удалённые изображения ​

Рецепты, которым не нужен плагин сборщика: командная строка, готовый проект, который не хочется менять, CDN и удалённые изображения и проверка для CI. Выбрать рецепт поможет страница Выбор способа.

Везде нужен sharp, а для вывода ThumbHash ещё и thumbhash:

bash
npm install -D sharp thumbhash

Плейсхолдеры для готового проекта ​

Когда применять. Проект уже написан. Нужны размытия без добавления плагина и без правки шаблонов вручную — например, со сборщиком, который не Vite.

bash
npx vue-image-kit placeholders --dry-run
npx vue-image-kit placeholders

Один раз зарегистрируйте манифест, который она пишет:

ts
import { VImageKitPlugin } from '@macrulez/vue-image-kit'
import placeholders from './image-placeholders'

app.use(VImageKitPlugin, { placeholders })

Что вы получите. Каждый <VImage> со статически известным изображением получает плейсхолдер и размер. Изображения из public/, с CDN или другого хоста попадают в манифест; изображения, импортированные в компонент, записываются в их шаблон как пропсы. --dry-run сначала показывает все изменения, а файл с незакоммиченными изменениями git никогда не правится. См. Плейсхолдеры для готовой вёрстки.

Изображения, путь которых приходит из данных ​

Когда применять. src собирается во время выполнения, и сканирование шаблонов его не находит.

bash
npx vue-image-kit placeholders --dir public/images --dir content/photos=https://cdn.example.com/photos

Что вы получите. Каждое изображение из папок добавляется в манифест под тем URL, по которому оно отдаётся: по пути от public/ или с urlPrefix, указанным после =. Запускайте команду заново, когда изображения меняются; неизменённые файлы берутся из кеша. Чтобы это делалось при каждой сборке само, используйте рецепт для Vite или Nuxt.

CDN и удалённые изображения ​

Когда применять. Изображения лежат на CDN или другом хосте.

bash
npx vue-image-kit placeholders --remote --hosts res.cloudinary.com --limit 200
npx vue-image-kit placeholders --url https://cdn.example.com/hero.jpg
  • --remote дополнительно скачивает CDN- и удалённые изображения, найденные при сканировании. По умолчанию выключено: в проекте таких изображений могут быть тысячи. --hosts ограничивает набор хостами, а --limit задаёт, сколько изображений скачать за один запуск, — так большой проект можно обработать частями.
  • --url добавляет одно названное изображение и скачивает его без --remote — само указание адреса и есть согласие.

Что вы получите. У распознаваемого CDN запрашивается версия шириной 128px, а настоящий размер читается из первых 64 КБ оригинала. Остальные хосты скачиваются целиком, не больше --max-bytes. Скачанные изображения кешируются до --refresh-remote.

Другой вид плейсхолдера и настройка ​

Когда применять. Нужен ThumbHash, только цвет или другая степень детализации.

bash
npx vue-image-kit placeholders --mode thumbhash
npx vue-image-kit placeholders --mode color
npx vue-image-kit placeholders --components 6x4 --sample 128 --color average

--mode выбирает, что хранит каждая запись. --components, --sample и --color описаны в разделе Настройка хешей.

Замена имеющихся плейсхолдеров ​

Когда применять. В шаблонах есть написанные вручную или устаревшие плейсхолдеры, и их нужно пересчитать все.

bash
npx vue-image-kit placeholders --replace --dry-run

Что вы получите. Статические атрибуты hazehash, blurhash, thumbhash, placeholder, placeholder-color и placeholder-mode заменяются плейсхолдером выбранного --mode. Значения, привязанные к выражению, и проп image не трогаются и перечисляются в сводке.

Адаптивные варианты без плагина ​

Когда применять. Нужны уменьшенные файлы WebP/AVIF, которые делает команда — из скрипта или в CI.

bash
npx vue-image-kit generate \
  --input ./src/images \
  --output ./public/images \
  --widths 400,800,1200 \
  --formats jpg,webp,avif \
  --manifest ./src/assets/images.ts

Что вы получите. Уменьшенные файлы и TypeScript-манифест. --watch перезапускает команду при изменениях, а --incremental пропускает неизменённые файлы. См. Генерация изображений.

Общий файл конфигурации ​

Когда применять. Несколько команд, скриптов и плагин Vite должны использовать одни и те же настройки.

js
// vue-image-kit.config.js
export default {
  input: './src/images',
  output: './public/images',
  widths: [400, 800, 1200],
  placeholders: {
    mode: 'blurhash',
    dirs: ['public/images'],
    tuning: { components: [4, 3] },
  },
}

Что вы получите. Каждая команда читает из файла свою секцию, а флаги командной строки важнее файла.

Отчёт об использовании в CI ​

Когда применять. Нужно узнать, как используются изображения, и ронять сборку, если чего-то не хватает.

bash
npx vue-image-kit scan
npx vue-image-kit scan --fail-on missing-alt,missing-file

Что вы получите. Сводку по каждому <VImage>, v-lazy-img и вызову composable, откуда берётся каждое изображение, и предупреждения: нет alt, нет размера, нет плейсхолдера. --fail-on заставляет команду завершиться с кодом 1, если найдено одно из перечисленных предупреждений. См. Отчёт об использовании.

Фоны через v-lazy-img и useBackgroundImage ​

Когда применять. Изображения задаются как CSS-фоны, а не через <VImage>.

bash
npx vue-image-kit placeholders

Что вы получите. С зарегистрированным манифестом v-lazy-img и useBackgroundImage() показывают размытие и доминирующий цвет записи, пока грузится изображение, а команда заполняет манифест для их использований со статическим src из public/, с CDN или другого хоста.