vite-plugin-unused-images

English | 中文

A lightweight, zero-config Vite plugin that finds unused image assets in your project and reports them in a developer-friendly way.

✨ Features

• ⚡ Runs automatically at build time, works out-of-the-box
• 🎯 Supports PNG, JPG, SVG, WebP and all common formats
• 🔧 Customizable scan directories, exclude rules and output path
• 🎨 Colorized CLI output + detailed JSON report, perfect for CI
• 🚨 Optional “fail the build when unused images are found”

📦 Installation

bun i -D vite-plugin-unused-images

🚀 Quick Start

1. Add to your Vite config

// vite.config.ts
import { defineConfig } from 'vite'
import unusedImages from 'vite-plugin-unused-images'

export default defineConfig({
	plugins: [
		unusedImages({
			/* override any defaults if needed */
		})
	]
})

2. Run build

bun run build

Example terminal output:

🔍 Scanning for unused images...
📦 Found 3 unused images
📝 Report saved to unused-images.json

Unused images:
  - src/assets/logo-old.png  12 KB  2024-06-01
  - public/bg-unused.webp   89 KB  2024-05-28
  - src/assets/icons/x.svg   3 KB  2024-05-25

⚙️ Options

| Option | Type | Default | Description | | -------------- | ---------- | ----------------------------------------- | ------------------------------------------ | | imageDirs | string[] | ['src/assets','public'] | Directories to scan for images | | sourceDirs | string[] | ['src'] | Directories to scan for source code | | extensions | string[] | ['png','jpg','jpeg','gif','svg','webp'] | Image extensions to check | | exclude | string[] | [] | Glob patterns to ignore | | outputFile | string | 'unused-images.json' | Path to save the JSON report | | failOnUnused | boolean | false | Throw error if any unused images are found | | deleteUnused | boolean | false | Delete unused images from output directory |

Custom example

unusedImages({
	imageDirs: ['src/assets/images', 'src/assets/icons'],
	sourceDirs: ['src', 'docs'],
	extensions: ['png', 'svg'],
	exclude: ['**/node_modules/**', '**/*.d.ts'],
	outputFile: 'reports/unused-images.json',
	failOnUnused: true,
	deleteUnused: false
})

📊 Report Format

Generated JSON looks like:

{
	"timestamp": "2024-09-04T12:00:00.000Z",
	"unusedCount": 2,
	"unusedImages": [
		{
			"path": "src/assets/banner.png",
			"size": "42 KB",
			"lastModified": "2024-08-30"
		},
		{
			"path": "public/icons/close.svg",
			"size": "1 KB",
			"lastModified": "2024-08-28"
		}
	]
}

🧰 FAQ

| Problem | Cause | Solution | | ------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------- | | Dynamically imported images are flagged as unused | Path concatenation or variable references | Exclude the directory in exclude or explicitly reference the asset | | Remote CDN images are scanned | Plugin only scans local filesystem | No action needed—remote URLs are ignored |

📄 License

MIT © 2024-present

🤝 Contributing

Issues and PRs are welcome!
To develop locally:

git clone https://github.com/Sunrisies/vite-plugin-unused-images.git
cd vite-plugin-unused-images
bun install