Registry / serialization / vite-plugin-purge-icons

vite-plugin-purge-icons

library0.10.0jsnpmunverified

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.

serialization devops

npm install vite-plugin-purge-icons

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-PURGE-

vite-plugin-purge-icons

serializationjavascriptv0.10.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–223 runs

build_error

glibc

node 18–223 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

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

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

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

PurgeIcons

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

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

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

@purge-icons/generated

✓ import '@purge-icons/generated'

✗ import { generated } from '@purge-icons/generated'

This is a side-effect only import; the package has no exports. Do not destructure.

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')

Debug

Known issues

breakingVite 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.

affects: <0.5.0

gotchaWhen @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.

affects: all

gotchaThe 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.

affects: all

Errors

Common errors & fixes

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

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.

ERR_PNPM_NO_MATCHING_VERSION... @iconify/json

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

TypeError: PurgeIcons is not a constructor

Using named import { PurgeIcons } instead of default import

fix

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

Upgrade

Version history

0.10.0latest on npm

Audit

Dependencies

viterequiredpeer dependency: Vite >= 2 is required to use the plugin

@iconify/iconifyrequiredruntime dependency for rendering icons in browser

@iconify/jsonoptionaloptional dependency: provides local icon sets to avoid online fetch

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/antfu/purge-icons ↗

packagehttps://www.npmjs.com/package/vite-plugin-purge-icons ↗