vite-plugin-svg-spriter

1.0.0 verified Mon Apr 27 auth: no javascript

Vite plugin that builds an SVG sprite from a folder of individual SVGs and injects it into the root HTML. Version 1.0.0, stable. Uses svg-sprite internally for sprite generation and supports full svg-sprite configuration. Key differentiator: simple folder-based approach, no manual sprite management, and injects the sprite automatically via Vite's transformIndexHtml hook. Active maintenance.

Common errors

error TypeError: createSvgSpritePlugin is not a function ↓

cause Using require instead of import on an ESM-only package.

fix

Replace const createSvgSpritePlugin = require(...) with import createSvgSpritePlugin from 'vite-plugin-svg-spriter'

error Error: ENOTDIR: not a directory, scandir '/path/to/svg-folder' ↓

cause The svgFolder option points to a file, not a directory.

fix

Ensure svgFolder is a directory containing the SVG files.

error Error: Cannot find module 'vite-plugin-svg-spriter' ↓

cause Package not installed due to typo in package name (e.g., 'sprite' instead of 'spriter').

fix

Install correct package: npm install vite-plugin-svg-spriter -DE

error Warning: [vite-plugin-svg-spriter] No SVG files found in /path/to/... ↓

cause The svgFolder directory is empty or does not contain .svg files.

fix

Place at least one SVG file in the specified folder.

Warnings

gotcha Package name is spelled with 'spriter' (r before e), not 'sprites' or 'sprite'. Incorrect install will fail. ↓

fix Verify npm install command: npm install vite-plugin-svg-spriter -DE

gotcha Plugin only works with Vite; not compatible with other bundlers (Webpack, Rollup standalone). ↓

fix Only use within a Vite project.

deprecated Using xlinkHref in SVG <use> is deprecated in SVG 2; use href instead. ↓

fix Use href="#thumbs-up" instead of xlinkHref="#thumbs-up".

gotcha Ensure svgFolder path is absolute and exists; relative paths may fail silently. ↓

fix Use path.resolve to construct absolute paths.

breaking ESM-only since v1.0.0; CommonJS require() will throw a runtime error. ↓

fix Switch to ES module syntax (import/export) and ensure your project is configured for ESM.

Install

npm install vite-plugin-svg-spriter

yarn add vite-plugin-svg-spriter

pnpm add vite-plugin-svg-spriter

Imports

createSvgSpritePlugin

wrong

const createSvgSpritePlugin = require('vite-plugin-svg-spriter')

correct

import createSvgSpritePlugin from 'vite-plugin-svg-spriter'

CommonJS require will fail; package is ESM-only as it exports a function using export default.

SvgSpritePluginOptions

wrong

const SvgSpritePluginOptions = require('vite-plugin-svg-spriter').SvgSpritePluginOptions

correct

import type { SvgSpritePluginOptions } from 'vite-plugin-svg-spriter'

TypeScript type import only; not a runtime value.

Plugin

wrong

import { Plugin } from 'vite-plugin-svg-spriter'

correct

import type { Plugin } from 'vite'

Plugin is a Vite type; not exported from this package.

Quickstart

Configures the plugin with an SVG folder, optional svg-sprite config (e.g., SVGO optimization), and injection location.

// vite.config.ts
import { defineConfig } from 'vite'
import createSvgSpritePlugin from 'vite-plugin-svg-spriter'
import path from 'path'

const SVG_FOLDER_PATH = path.resolve(__dirname, 'src', 'assets', 'svg-sprite')

export default defineConfig({
  plugins: [
    createSvgSpritePlugin({
      svgFolder: SVG_FOLDER_PATH,
      svgSpriteConfig: {
        shape: {
          transform: ['svgo']
        }
      },
      transformIndexHtmlTag: {
        injectTo: 'body'
      }
    })
  ]
})