Choosing an Approach

Image Kit can prepare images in several ways, and most tasks can be solved by more than one of them. This page lists what each approach does, so you can pick one and jump to a ready-made configuration.

Two separate jobs are easy to mix up:

• Responsive variants — resizing a source image into several widths and formats (400w, 800w, WebP, AVIF …) so the browser downloads the smallest suitable file.
• Placeholders — a tiny HazeHash, BlurHash, ThumbHash or dominant color, plus the image size, shown while the real image loads. Nothing is resized and no file is written.

You can use either job on its own or both together. If a project only needs a blur while images load, it never has to generate variants.

What do you need?

• A blur while images load, for a few images that you import — use a placeholder-only import.
• A blur for many images in a folder, picked by file name — use import.meta.glob.
• A blur for images whose path comes from data (:src="item.image", a CMS, a JSON file) — use the placeholders manifest from folders. In Nuxt it is one option.
• Resized WebP/AVIF variants built ahead of time — use the batch generation of the Vite plugin or the generate command.
• Resized variants made on request, with no build step — use the on-demand server or the Nuxt route.
• Placeholders for an existing project, without touching its build — run the placeholders command.
• Images on a CDN or another host — use urls or --url.
• Find out how images are used before changing anything — run scan.

The approaches side by side

Approach	Writes files	Runs at	Works with a runtime-built src	Needs
?placeholder (a field list), ?hazehash, ?blurhash, ?color, ?size, ?preview	no	build / dev	no — one import per image	Vite plugin, sharp
import.meta.glob with ?placeholder	no	build / dev	by file name	Vite plugin, sharp
Manifest from dirs / urls	no	build / dev	yes	Vite plugin or Nuxt, sharp
placeholders command	the manifest or your templates	when you run it	with --dir / --url	sharp
?vik import	yes	build / dev	no	Vite plugin, sharp
Batch generation (generate)	yes	build / dev	yes — files exist on disk	Vite plugin or CLI, sharp
On-demand server	cache only	on each request	yes	a Node server, sharp

thumbhash is also needed wherever a ThumbHash is computed. See Installation.

How a placeholder reaches <VImage>

Every approach ends in one of three ways, and it helps to know which you are using:

• Props — the values are passed to the component directly: v-bind="placeholder", :hazehash="hash", or written into the template by the command.
• Manifest — a src → placeholder map is registered once, and <VImage> finds its entry by the exact src string. No per-usage props. See Placeholders manifest.
• Variants metadata — a ?vik import or a generated manifest carries the placeholder together with the resized URLs, and is passed as the image prop.

An image imported into a component (import hero from './hero.jpg') gets a hashed URL when the app is built, so a manifest lookup by src can never find it. Use props for those, or serve the image from a folder with a fixed URL.

Recipes

• Vite and Vue — every plugin configuration, from a bare blur to variants and a folder manifest together.
• Nuxt — the module options, and when the Vite plugin has to be added by hand.
• CLI, CDN and remote images — projects without the plugin, CDN images, a CI report.