vite-plugin-svg-icons-ng

1.8.1 verified Mon Apr 27 auth: no javascript

Vite plugin to generate an SVG sprite from a set of SVG files and inject it into the HTML at build time or mount it in development via a virtual module. v1.8.1 is the current stable release, with active development and regular releases. It supports Vite >=5 and Node >=18. Key differentiators: file-based icon management, efficient HMR with cached compilation, SSR-friendly sprite injection, duplicate symbol detection, and virtual modules (register, ids, sprite). Compared to alternatives like vite-plugin-svg-icons, this is a modern fork with improved TypeScript types and a cleaner virtual module API. TypeScript ready.

Common errors

error Error: Cannot find module 'virtual:svg-icons/register' or its corresponding type declarations. ↓

cause TypeScript cannot resolve the virtual module without a proper declaration.

fix

Add a declaration file (e.g., src/vite-env.d.ts) with: /// <reference types="vite-plugin-svg-icons-ng/client" />

error TypeError: createSvgIconsPlugin is not a function ↓

cause Package is ESM-only; using CommonJS require() causes the import to fail.

fix

Switch to ESM imports: import { createSvgIconsPlugin } from 'vite-plugin-svg-icons-ng'

error [Vite] The virtual module 'virtual:svg-icons-register' has been deprecated and will be removed in v2.0.0. ↓

cause Using the old dash-based virtual module id.

fix

Use the new slash-based id: import 'virtual:svg-icons/register'

Warnings

deprecated Virtual module ids with dashes (e.g., 'virtual:svg-icons-register') are deprecated and will be removed in v2.0.0. ↓

fix Update imports to use slash-based paths: 'virtual:svg-icons/register', 'virtual:svg-icons/ids', 'virtual:svg-icons/sprite'.

breaking v1.7.0 changed the default value of 'symbolId' from 'icon-[name]' to 'icon-[dir]-[name]' to prevent collisions. ↓

fix If you relied on the previous default, set symbolId explicitly: symbolId: 'icon-[name]'.

gotcha The plugin requires Vite >=5.0.0; using it with Vite 4 will cause runtime errors. ↓

fix Upgrade Vite to version 5 or later.

gotcha When using monorepos, relative iconDirs resolve from the Vite project root (not the package root). This can cause icons not to be found. ↓

fix Use absolute paths for iconDirs when the icon directory is outside the current app root: iconDirs: [path.resolve(__dirname, '../../shared/icons')].

Install

npm install vite-plugin-svg-icons-ng

yarn add vite-plugin-svg-icons-ng

pnpm add vite-plugin-svg-icons-ng

Imports

createSvgIconsPlugin
wrong
```
const createSvgIconsPlugin = require('vite-plugin-svg-icons-ng')
```
correct
```
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons-ng'
```
ESM-only package; CommonJS require is not supported as the package is type: 'module' and uses ESM exports.
virtual:svg-icons/register
wrong
```
import 'virtual:svg-icons-register'
```
correct
```
import 'virtual:svg-icons/register'
```
The deprecated virtual module id 'virtual:svg-icons-register' (with dash) is removed in v2; use the slash-based path. In v1.x it still works but emits a deprecation warning.
VitePluginSvgIconsNgOptions
```
import type { VitePluginSvgIconsNgOptions } from 'vite-plugin-svg-icons-ng'
```
Type import for options; useful when defining plugin config in TypeScript files.

Quickstart

Shows how to configure the Vite plugin with a custom symbol ID pattern and SVGO options, then import the virtual register module in the app entry.

import { defineConfig } from 'vite';
import { createSvgIconsPlugin } from 'vite-plugin-svg-icons-ng';
import path from 'path';

export default defineConfig({
  plugins: [
    createSvgIconsPlugin({
      iconDirs: [path.resolve(process.cwd(), 'src/icons')],
      symbolId: 'icon-[dir]-[name]',
      svgoOptions: {
        multipass: true,
        plugins: ['preset-default', 'removeTitle', 'removeDesc']
      }
    })
  ]
});

// In your entry file (e.g., main.ts):
import 'virtual:svg-icons/register';