Vite-plugin-svg-combiner NPM

vite-plugin-svg-combiner

Another SVG sprites plugin for Vite/Rollup. Inspired by vite-plugin-svg-sprite.

Features

Combine SVG files into one sprite file
Support runtime and file mode
Allow to customize sprite element id
Allow to customize symbol id
Allow to customize sprite file name

Install

npm i -D vite-plugin-svg-combiner

Usage

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

export default defineConfig({
  plugins: [
    svgCombiner({
      include: ['src/assets/icons/**/*.svg'],
    }),
  ],
})

Options

include

Type: string | string[] | RegExp | RegExp[]
Files to be processed. See @rollup/pluginutils.
Required

exclude

Type: string | string[] | RegExp | RegExp[]
Files to be excluded. See @rollup/pluginutils.
Default: undefined

emitFile

Type: boolean | string
Whether to emit sprite file.
- If true, which means file mode, the sprite file will be emitted to the output directory, the default sprite file name is svg-sprite.svg.
- If false, which means runtime mode, the sprite file will be injected to the bundle. And insert to the DOM automatically.
- If a string, the sprite file will be emitted to the specified path. The path is relative to the output directory.
Default: false

symbolId

Type: string | ((filePath: string) => string)
Customize symbol id.
- If a string, the symbol id will be the specified string.
- If a function, the symbol id will be the return value of the function.
Some variables can be used in the string or function:
- [dirname]: The directory name of the SVG file. eg: a/b/c/d.svg -> a-b-c.
- [name]: The name of the SVG file. eg: a/b/c/d.svg -> d.
When symbolId is a function, the function will be called with the SVG file path as the first argument. The SVG file path is relative to the baseDir option.
Default: [name]

baseDir

Type: string | ((id: string) => string)
The base directory of the SVG files. The SVG file path is relative to the baseDir option.
When baseDir is a function, the function will be called with the absolute path of the SVG file as the first argument.
You can set baseDir to empty string if you want to use the absolute path of the SVG file as the symbol id.
Default: process.cwd()

svgoConfig

Type: object | string
The SVGO config. If a string, the config will be loaded from the specified file.
Note: The loaded config will be merged with the default config using deepmerge.

Default:

{
  plugins: [
    {
      name: "preset-default",
      params: {
        overrides: {
          removeViewBox: false, // keep viewBox attr
        },
      },
    },
    "cleanupIds", // clean up ids, we will use symbol id instead
    "removeDimensions", // remove width/height attributes, set viewBox instead
    "removeXMLNS", // remove xmlns attribute
  ],
}

Example

Runtime mode

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

export default defineConfig({
  plugins: [
    svgCombiner({
      include: ['src/assets/icons/*.svg'],
      emitFile: false,
    }),
  ],
})

File mode

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

export default defineConfig({
  plugins: [
    svgCombiner({
      include: ['src/assets/icons/*.svg'],
      emitFile: true, // or a string like 'assets/sprite.svg'
    }),
  ],
})

Custom symbol id

// vite.config.js
import { fileURLToPath } from "url";

import { defineConfig } from 'vite'
import svgCombiner from 'vite-plugin-svg-combiner'

export default defineConfig({
  plugins: [
    svgCombiner({
      include: ['src/assets/icons/**/*.svg'],
      symbolId: 'icon-[name]',
      baseDir: fileURLToPath(new URL('src/assets/icons', import.meta.url)),
    }),
  ],
})

Custom symbol id function

// vite.config.js
import { fileURLToPath } from "url";

import { defineConfig } from 'vite'
import svgCombiner from 'vite-plugin-svg-combiner'

export default defineConfig({
  plugins: [
    svgCombiner({
      include: ['src/assets/icons/**/*.svg'],
      symbolId: (filePath) => {
        // filePath do not contain directory
        if (!filePath.includes('/')) {
          return `icon-[name]`
        }

        return `icon-[dirname]-[name]`
      },
      baseDir: fileURLToPath(new URL('src/assets/icons', import.meta.url)),
    }),
  ],
})

Custom svgo config

// vite.config.js
import { fileURLToPath } from "url";

import { defineConfig } from 'vite'
import svgCombiner from 'vite-plugin-svg-combiner'

export default defineConfig({
  plugins: [
    svgCombiner({
      include: ['src/assets/icons/**/*.svg'],
      svgoConfig: fileURLToPath(new URL('svgo.config.js', import.meta.url)),
    }),
  ],
})