vite-plugin-vue-images

0.6.1 verified Mon Apr 27 auth: no javascript maintenance

Auto-import images into Vue templates for Vite projects, eliminating manual imports for Vite 2 + Vue 3. Version 0.6.1 is current, with a maintenance-level release cadence. Unlike manual imports, this plugin resolves images from configured directories and transforms template references into automatically imported variables. Key differentiator: convention-based image discovery with PascalCase naming and subdirectory prefix support. Limited to Vite 2 and Vue 3; no longer actively developed.

Common errors

error Error: Cannot find module 'vite-plugin-vue-images' ↓

cause Package not installed or incorrect import path.

fix

Run 'npm install -D vite-plugin-vue-images' and import as 'import ViteImages from "vite-plugin-vue-images"'.

error If you are using Vite 3+, this plugin is not compatible. ↓

cause Plugin only supports Vite 2.

fix

Switch to Vite 2 project or use an alternative image auto-import plugin.

error Uncaught (in promise) ReferenceError: ImageName is not defined ↓

cause Image variable not auto-imported due to incorrect dirs configuration or extension not supported.

fix

Verify the image file is in one of the dirs, has an allowed extension, and the name matches after PascalCase conversion.

Warnings

breaking Only works with Vite 2 and Vue 3; incompatible with Vite 3+ or Vue 2. ↓

fix Upgrade to a Vite 2 project or use an alternative plugin for Vite 3+.

gotcha Variables (props, data) will be clobbered in templates if they conflict with image names. ↓

fix Avoid naming Vue component data or props with the same PascalCase name as image files.

gotcha Only works with v-bind:src or :src; not with normal src="Image1". ↓

fix Always use :src for image references in templates.

gotcha Duplicate image names across directories are not supported; last one wins. ↓

fix Ensure unique file names across all configured image directories.

Install

npm install vite-plugin-vue-images

yarn add vite-plugin-vue-images

pnpm add vite-plugin-vue-images

Imports

ViteImages (default)

wrong

const ViteImages = require('vite-plugin-vue-images')

correct

import ViteImages from 'vite-plugin-vue-images'

ESM-only; CommonJS require will fail.

Options (type)

wrong

import { Options } from 'vite-plugin-vue-images'

correct

import type { Options } from 'vite-plugin-vue-images'

Type-only import; avoid runtime value import.

ViteImages in vite.config.ts

wrong

import ViteImages from 'vite-plugin-vue-images'
export default defineConfig({ plugins: [Vue(), ViteImages({ dirs: 'src/assets/img' })] })
// Wrong: dirs must be an array

correct

import ViteImages from 'vite-plugin-vue-images'
export default defineConfig({ plugins: [Vue(), ViteImages()] })

dirs option must be array of strings.

Quickstart

Configure the plugin in vite.config.ts and use images in Vue templates without explicit imports.

// vite.config.js
import { defineConfig } from 'vite'
import Vue from '@vitejs/plugin-vue'
import ViteImages from 'vite-plugin-vue-images'

export default defineConfig({
  plugins: [
    Vue(),
    ViteImages({
      dirs: ['src/assets/img'],
      extensions: ['jpg', 'jpeg', 'png', 'svg', 'webp']
    })
  ]
})

// Any Vue component can now use images directly:
// <template>
//   <img :src="MyImage" />
// </template>
// where src/assets/img/my_image.jpg becomes MyImage