CLI — Usage Report

npx vue-image-kit scan walks the whole project and reports how vue-image-kit is used: where every image comes from, which VImage props are in play, and what's worth fixing — missing alt, no size, no placeholder, a file that doesn't exist.

npx vue-image-kit scan

Needs nothing beyond vue itself — .vue files are parsed with the project's own vue/compiler-sfc.

What it finds

• <VImage> in templates — as VImage or v-image, or under a local import alias (import { VImage as Img } from '@macrulez/vue-image-kit'). A VImage imported from a different library is ignored.
• <VImage> in JSX/TSX and in h(VImage, …) render functions.
• v-lazy-img directives, including a locally renamed directive.
• useImage() and useBackgroundImage() calls. A same-named composable imported from another package (e.g. VueUse's useImage) is ignored; a call with no import at all (Nuxt auto-imports) is counted.

Every prop is recorded with its value when it can be worked out statically — a string or number literal, a const declared in the same file, an imported file — and as the original expression otherwise.

Image sources

Each usage gets one source type:

• public — an absolute path like /images/hero.jpg, served from public/. The file is looked up on disk.
• local-import — an image imported into the component (import hero from '@/assets/hero.jpg'). Aliases come from tsconfig paths, vite.config resolve.alias and the Vue/Nuxt defaults (@ → src; ~/@ → the Nuxt source directory).
• cdn:<provider> — a URL on one of the CDNs autoLoader() recognizes, e.g. cdn:cloudinary.
• remote — any other http(s):// URL.
• vik — build-time metadata: :image bound to a ?vik import or a manifest entry from generate.
• server — a path served through the self-hosted on-demand server (loader="server").
• data-uri — an inline data: URL.
• dynamic — a value only known at runtime, such as item.src inside a v-for.

A SrcSet object ({ avif, webp, fallback }) is classified by its fallback.

Report

[vue-image-kit] scan — 8 usages in 1 file (2 scanned)

By source
  Source        Usages  VImage  w/ size  w/ placeholder  eager
  ────────────  ──────  ──────  ───────  ──────────────  ─────
  public             5       5        2               1      0
  dynamic            1       1        0               0      0
  local-import       1       1        0               0      0
  remote             1       1        0               0      0

Files
  File         Usages  VImage  v-lazy-img  composables
  ───────────  ──────  ──────  ──────────  ───────────
  src/App.vue       8       8           0            0

VImage props
  alt 8 · src 8 · height 2 · width 2 · blurhash 1 · sizes 1

Warnings
     6 × no-dimensions — no width/height — the browser cannot reserve space (layout shift)
         src/App.vue:10
         src/App.vue:16
         src/App.vue:17
         … 3 more (use --details)
     7 × no-placeholder — no placeholder (hazehash/blurhash/thumbhash/placeholder/placeholderColor)
         …
     1 × missing-file — referenced file does not exist
         src/App.vue:21

  5 usages without a placeholder can be filled in by `vue-image-kit placeholders`.
  1 usage has a source that can't be resolved statically (shown as "dynamic").

• By source — usages per source type; for VImage usages, how many have a size (width + height, or image), a placeholder, and load eagerly (priority or :lazy="false").
• Files — the files with the most usages (--top controls how many).
• VImage props — how often each VImage prop is used; plain attributes like class or key aren't counted.
• Warnings — grouped by code, with the first locations of each.

Warnings

• missing-alt — VImage without alt.
• empty-alt — alt="", fine only for purely decorative images.
• no-dimensions — neither width/height nor image (and not layout="fill"), so the browser can't reserve the image's space.
• no-placeholder — none of hazehash, blurhash, thumbhash, placeholder, placeholderColor, image, or placeholderMode="color"/"shimmer".
• missing-file — a public/ path or a local import that points at a file that doesn't exist.
• multiple-priority — more than one priority image in the same file.
• widths-without-sizes — widths without sizes or width, so the browser assumes the image spans the whole viewport.
• local-without-vik — a local image imported without ?vik; the Vite plugin would give it a size and placeholder at build time.

A usage that spreads its props (v-bind="attrs") skips the prop-based checks, since its props can't be known statically.

Options

• --root <dir> · default: the current directory. Project root to scan.
• --include <globs> · default: **/*.{vue,js,jsx,ts,tsx,mjs,mts,cjs,cts}. Comma-separated globs of files to scan.
• --exclude <globs> — extra comma-separated globs to skip. node_modules, dist, .nuxt, .output, coverage, *.d.ts and test files (*.test.*, *.spec.*) are always skipped.
• --public-dir <dir> · default: public. Where /… paths are looked up.
• --alias <key=path> — a path alias, repeatable (--alias @=src). Adds to the aliases read from tsconfig and vite.config.
• --package <name> — an extra package name to treat as vue-image-kit, repeatable — for a project that imports it through its own alias.
• --no-vite-config — don't load vite.config to read resolve.alias.
• --details — also list every usage, and every location of each warning.
• --top <n> · default: 10. How many files the files table shows.
• --format <fmt> · default: table. table, json, md or csv.
• --out <file> — write the report to a file instead of the terminal.
• --fail-on <codes> — exit with code 1 if any of these warnings is found; comma-separated codes, or any.

Example — a Markdown report and a CI check:

npx vue-image-kit scan --details --format md --out image-report.md
npx vue-image-kit scan --fail-on missing-alt,missing-file

--format json writes the summary, every warning and every usage with its props and source; --format csv writes one row per usage.

Config file

The same settings can live under scan in vue-image-kit.config.js:

// vue-image-kit.config.js
export default {
  scan: {
    include: ['src/**/*.{vue,ts}'],
    exclude: ['src/legacy/**'],
    publicDir: 'static',
    aliases: { '#img': './src/assets/images' },
    packageNames: ['image-kit'],
    viteConfig: false,
  },
}