VueCraft NPM

CLI, CDN and Remote Images ​

Recipes that don't need a bundler plugin: the command line, an existing project you'd rather not change, CDN and remote images, and a check for CI. Choosing an Approach helps to pick one.

sharp is required for everything here, plus thumbhash for ThumbHash output:

bash
npm install -D sharp thumbhash

Placeholders for an existing project ​

When to use it. The project is already written. You want blurs without adding a plugin or editing any template by hand — for example with a bundler other than Vite.

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

Register the manifest it writes once:

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

app.use(VImageKitPlugin, { placeholders })

What you get. Every <VImage> with a statically known image gets a placeholder and its size. Images from public/, a CDN or another host go into the manifest; images imported into a component are written into their template as props. --dry-run prints every change first, and a file with uncommitted git changes is never edited. See Placeholders for Existing Images.

Images whose path comes from data ​

When to use it. The src is built at runtime, so scanning templates can't find it.

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

What you get. Every image in the folders is added to the manifest under the URL it is served at: its path from public/, or the urlPrefix given after =. Re-run the command when the images change; unchanged files come from the cache. To have this done on every build instead, use the Vite or Nuxt recipe.

CDN and remote images ​

When to use it. Images are on a CDN or another host.

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 also downloads the CDN and remote images the scan found. It is off by default, since a project can reference thousands of them. --hosts restricts it to some hosts, and --limit makes a run download at most that many, so a large project can be done in batches.
  • --url adds one named image and downloads it without --remote — naming it is the consent.

What you get. A recognised CDN is asked for a 128px rendition, and its real size is read from the first 64 KB of the original. Other hosts are downloaded whole, up to --max-bytes. Downloaded images are cached until --refresh-remote.

Another kind of placeholder, and tuning ​

When to use it. You want a ThumbHash, only a color, or a different amount of detail.

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 picks what each entry carries. --components, --sample and --color are explained in Tuning the hashes.

Replacing placeholders you already have ​

When to use it. Templates have hand-written or outdated placeholders, and you want them all recomputed.

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

What you get. Static hazehash, blurhash, thumbhash, placeholder, placeholder-color and placeholder-mode attributes are replaced by the chosen --mode. Values bound to an expression and the image prop are left alone and listed in the summary.

Responsive variants without a plugin ​

When to use it. You want resized WebP/AVIF files made by a command, from a script or in 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

What you get. The resized files and a TypeScript manifest. --watch re-runs on changes and --incremental skips unchanged files. See Generate Images.

One shared configuration file ​

When to use it. Several commands, scripts and the Vite plugin should use the same settings.

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] },
  },
}

What you get. Each command reads its own section from the file; flags on the command line take precedence over it.

A usage report in CI ​

When to use it. You want to know how images are used — and fail the build when something is missing.

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

What you get. A summary of every <VImage>, v-lazy-img and composable call, where each image comes from, and warnings such as a missing alt, no size or no placeholder. --fail-on makes the command exit with code 1 when a listed warning is found. See Usage Report.

Backgrounds with v-lazy-img and useBackgroundImage ​

When to use it. Images are set as CSS backgrounds rather than through <VImage>.

bash
npx vue-image-kit placeholders

What you get. With a registered manifest, v-lazy-img and useBackgroundImage() show the entry's blur and dominant color while the image loads, and the command fills the manifest for their usages with a static src from public/, a CDN or another host.