{"id":22864,"library":"vite-plugin-svg-combiner","title":"vite-plugin-svg-combiner","description":"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.","status":"active","version":"0.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/kuoruan/vite-plugin-svg-combiner","tags":["javascript","vite","svg","sprite","svg-sprite","svg-sprites","combiner","svg-combiner","plugin","typescript"],"install":[{"cmd":"npm install vite-plugin-svg-combiner","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-svg-combiner","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-svg-combiner","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required by Vite plugins with Rollup integration","package":"rollup","optional":false},{"reason":"Peer dependency - core bundler plugin target","package":"vite","optional":false}],"imports":[{"note":"This package is ESM-only since v0.6.0; CommonJS require will fail. Use import.","wrong":"const svgCombiner = require('vite-plugin-svg-combiner')","symbol":"svgCombiner","correct":"import svgCombiner from 'vite-plugin-svg-combiner'"},{"note":"The default export is the plugin function; named export does not exist.","wrong":"import { svgCombiner } from 'vite-plugin-svg-combiner'","symbol":"svgCombiner (default export)","correct":"import svgCombiner from 'vite-plugin-svg-combiner'"},{"note":"Type-only import for TypeScript; the option interface is not a runtime value.","wrong":"import { VitePluginSvgCombinerOptions } from 'vite-plugin-svg-combiner'","symbol":"VitePluginSvgCombinerOptions (TypeScript)","correct":"import type { VitePluginSvgCombinerOptions } from 'vite-plugin-svg-combiner'"}],"quickstart":{"code":"// vite.config.js\nimport { defineConfig } from 'vite'\nimport svgCombiner from 'vite-plugin-svg-combiner'\n\nexport default defineConfig({\n  plugins: [\n    svgCombiner({\n      include: ['src/assets/icons/*.svg'],\n      // runtime mode (default): injects sprite into HTML\n      // file mode: set emitFile: true or 'path/sprite.svg'\n      symbolId: '[name]', // default uses file name\n      svgoConfig: {\n        plugins: [\n          'removeDimensions',\n          { name: 'sortAttrs', params: { order: ['id', 'viewBox', 'xmlns'] } }\n        ]\n      }\n    })\n  ]\n})","lang":"javascript","description":"Basic setup with runtime mode, custom symbol ID, and additional SVGO plugin."},"warnings":[{"fix":"Convert project to ESM or use dynamic import(). Ensure node >=16.","message":"v0.6.0 switched to ESM-only package. CJS require() will throw ERR_REQUIRE_ESM.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Explicitly set symbolId to '[name]' to keep current behavior.","message":"The option 'symbolId' default is '[name]' but in future versions may default to '[dirname]-[name]' to avoid collisions.","severity":"deprecated","affected_versions":">=0.5.0 <0.7.0"},{"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.","message":"The plugin uses @rollup/pluginutils; include patterns are relative to project root, but baseDir option can change the reference point for symbol IDs.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Set svgoConfig.plugins to exclude 'cleanupIds' or add 'cleanupIds' with 'remove: false' if you need to preserve original IDs.","message":"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).","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use a unique string for emitFile, e.g., emitFile: 'icons/sprite.svg'.","message":"In file mode (emitFile: true or string), the emitted sprite file name may conflict with other assets if not unique.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Change to `import svgCombiner from 'vite-plugin-svg-combiner'` or use dynamic import.","cause":"Using require() on an ESM-only package (v0.6.0+).","error":"ERR_REQUIRE_ESM"},{"fix":"Verify that the include pattern is correct and relative to project root, e.g., 'src/assets/*.svg'. Use absolute paths or adjust baseDir.","cause":"Glob patterns in include option do not match any files.","error":"Error: [vite] Rollup failed to resolve include patterns\n    at ..."},{"fix":"Use default import: `import svgCombiner from 'vite-plugin-svg-combiner'`.","cause":"Named import instead of default import: `import { svgCombiner }`.","error":"TypeError: svgCombiner is not a function"},{"fix":"Run `npm install -D vite-plugin-svg-combiner`.","cause":"Package not installed or missing from package.json dependencies.","error":"Module not found: Can't resolve 'vite-plugin-svg-combiner'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}