vite-plugin-svg-combiner

0.6.0 verified Mon Apr 27 auth: no javascript

A Vite/Rollup plugin that combines multiple SVG files into a single SVG sprite, supporting both runtime injection and emitted file modes. Current stable version 0.6.0 requires Node >= 16, Vite >= 2.0.0, and Rollup >= 2.0.0. This ESM-only package offers customizable symbol IDs (using dirname/name variables), built-in SVGO optimization (preserving viewBox, cleaning IDs, removing dimensions/XMLNS), and flexible include/exclude patterns via @rollup/pluginutils. Compared to alternatives like vite-plugin-svg-sprite, it provides dual runtime/file modes and deeper SVGO configuration options.

Common errors

error ERR_REQUIRE_ESM ↓

cause Using require() on an ESM-only package (v0.6.0+).

fix

Change to import svgCombiner from 'vite-plugin-svg-combiner' or use dynamic import.

error Error: [vite] Rollup failed to resolve include patterns at ... ↓

cause Glob patterns in include option do not match any files.

fix

Verify that the include pattern is correct and relative to project root, e.g., 'src/assets/*.svg'. Use absolute paths or adjust baseDir.

error TypeError: svgCombiner is not a function ↓

cause Named import instead of default import: `import { svgCombiner }`.

fix

Use default import: import svgCombiner from 'vite-plugin-svg-combiner'.

error Module not found: Can't resolve 'vite-plugin-svg-combiner' ↓

cause Package not installed or missing from package.json dependencies.

fix

Run npm install -D vite-plugin-svg-combiner.

Warnings

breaking v0.6.0 switched to ESM-only package. CJS require() will throw ERR_REQUIRE_ESM. ↓

fix Convert project to ESM or use dynamic import(). Ensure node >=16.

deprecated The option 'symbolId' default is '[name]' but in future versions may default to '[dirname]-[name]' to avoid collisions. ↓

fix Explicitly set symbolId to '[name]' to keep current behavior.

gotcha The plugin uses @rollup/pluginutils; include patterns are relative to project root, but baseDir option can change the reference point for symbol IDs. ↓

fix When using baseDir, ensure include paths are relative to project root, not baseDir. Use baseDir to control how file paths map to symbol IDs.

gotcha SVGO cleanupIds plugin is enabled by default; custom IDs in SVG files are overwritten, which may break internal references (e.g., <use> within the same file). ↓

fix Set svgoConfig.plugins to exclude 'cleanupIds' or add 'cleanupIds' with 'remove: false' if you need to preserve original IDs.

gotcha In file mode (emitFile: true or string), the emitted sprite file name may conflict with other assets if not unique. ↓

fix Use a unique string for emitFile, e.g., emitFile: 'icons/sprite.svg'.

Install

npm install vite-plugin-svg-combiner

yarn add vite-plugin-svg-combiner

pnpm add vite-plugin-svg-combiner

Imports

svgCombiner

wrong

const svgCombiner = require('vite-plugin-svg-combiner')

correct

import svgCombiner from 'vite-plugin-svg-combiner'

This package is ESM-only since v0.6.0; CommonJS require will fail. Use import.

svgCombiner (default export)
wrong
```
import { svgCombiner } from 'vite-plugin-svg-combiner'
```
correct
```
import svgCombiner from 'vite-plugin-svg-combiner'
```
The default export is the plugin function; named export does not exist.

VitePluginSvgCombinerOptions (TypeScript)

wrong

import { VitePluginSvgCombinerOptions } from 'vite-plugin-svg-combiner'

correct

import type { VitePluginSvgCombinerOptions } from 'vite-plugin-svg-combiner'

Type-only import for TypeScript; the option interface is not a runtime value.

Quickstart

Basic setup with runtime mode, custom symbol ID, and additional SVGO plugin.

// vite.config.js
import { defineConfig } from 'vite'
import svgCombiner from 'vite-plugin-svg-combiner'

export default defineConfig({
  plugins: [
    svgCombiner({
      include: ['src/assets/icons/*.svg'],
      // runtime mode (default): injects sprite into HTML
      // file mode: set emitFile: true or 'path/sprite.svg'
      symbolId: '[name]', // default uses file name
      svgoConfig: {
        plugins: [
          'removeDimensions',
          { name: 'sortAttrs', params: { order: ['id', 'viewBox', 'xmlns'] } }
        ]
      }
    })
  ]
})