vite-plugin-purge-icons

0.10.0 verified Mon Apr 27 auth: no javascript

Vite plugin for PurgeIcons that bundles only the SVG icons you actually use, drastically reducing bundle size. Current stable version 0.10.0 works with Vite 2+. Maintained by Anthony Fu, released under MIT. Differentiators: tree-shakes icon sets from @iconify/json, supports local and online icon loading, and integrates seamlessly with Vue/React via import side effect. Supports Node >= 12, ships TypeScript types.

Common errors

error Error: Cannot find module '@purge-icons/generated' ↓

cause Missing the import of '@purge-icons/generated' in entry file or plugin not properly configured in vite.config

fix

Add 'import "@purge-icons/generated"' to your main JS/TS file and ensure the plugin is added to Vite config.

error ERR_PNPM_NO_MATCHING_VERSION... @iconify/json ↓

cause PNPM strict resolution; @iconify/json is optional and may not be installed by default

fix

Manually install @iconify/json as dev dependency: pnpm add -D @iconify/json

error TypeError: PurgeIcons is not a constructor ↓

cause Using named import { PurgeIcons } instead of default import

fix

Change to: import PurgeIcons from 'vite-plugin-purge-icons'

Warnings

breaking Vite 2 is supported from v0.5.x, Vite 1's support is discontinued ↓

fix Upgrade to v0.5.0 or later, and ensure Vite >= 2.

gotcha When @iconify/json is not installed, PurgeIcons fetches icons online, which may fail in offline/air-gapped environments ↓

fix Install @iconify/json as a dev dependency to use local icon sets.

gotcha The plugin only purges icons used in the application; icons used dynamically (e.g., via string concatenation) may be removed incorrectly ↓

fix Use static icon names or add them to the safelist in PurgeIcons options.

Install

npm install vite-plugin-purge-icons

yarn add vite-plugin-purge-icons

pnpm add vite-plugin-purge-icons

Imports

default

wrong

const PurgeIcons = require('vite-plugin-purge-icons')

correct

import PurgeIcons from 'vite-plugin-purge-icons'

ESM-only; CommonJS require will break in modern Vite setup. Use default import.

PurgeIcons

wrong

import { PurgeIcons } from 'vite-plugin-purge-icons'

correct

import PurgeIcons from 'vite-plugin-purge-icons'

This is a default export, not a named export. Named import yields undefined.

@purge-icons/generated
wrong
```
import { generated } from '@purge-icons/generated'
```
correct
```
import '@purge-icons/generated'
```
This is a side-effect only import; the package has no exports. Do not destructure.

Quickstart

Adds PurgeIcons plugin to Vite config and imports the generated icon bundle. Requires installing @iconify/iconify as runtime dep and @iconify/json as optional dev dep.

// vite.config.js
import { defineConfig } from 'vite'
import PurgeIcons from 'vite-plugin-purge-icons'

export default defineConfig({
  plugins: [
    PurgeIcons({
      /* optional: PurgeIcons options */
    })
  ]
})

// In your entry file (e.g., main.js)
import { createApp } from 'vue'
import App from './App.vue'
import '@purge-icons/generated'

createApp(App).mount('#app')