rollup-plugin-svg-sprites

1.2.5 verified Mon Apr 27 auth: no javascript

Rollup plugin for creating SVG sprites, built on top of svg-baker and svg-baker-runtime, sharing the same foundation as webpack's svg-sprite-loader. Current stable version is 1.2.5, with TypeScript support. It supports both Rollup and Vite, and offers special handling for Vue 3 and React. Key differentiators include query-based imports (.svg?vueComponent, .svg?jsx), support for large numbers of SVGs via require.context, and minimal configuration. Release cadence is periodic with multiple patches. It integrates with Vue 3, React, and standard SVG usage.

Common errors

error Error: Cannot find module 'svg-baker' ↓

cause Missing runtime dependency svg-baker

fix

npm install svg-baker

error Error: 'default' is not exported by node_modules/svg-baker/..., imported from ... ↓

cause CommonJS module not converted; @rollup/plugin-commonjs missing

fix

Add commonjs() plugin before svgSprites in rollup config.

error TypeError: Cannot read properties of undefined (reading 'id') ↓

cause Importing SVG without proper plugin setup or missing ?vueComponent/?jsx query

fix

Ensure svgSprites() is included and use correct import query for Vue/React.

error Module '"*.svg"' resolves to a non-module entity and cannot be imported using this construct. ↓

cause TypeScript cannot resolve SVG import types

fix

Add type declarations as shown in README: declare module '*.svg?vueComponent' { ... }

Warnings

gotcha Missing @rollup/plugin-commonjs breaks SVG import ↓

fix Add @rollup/plugin-commonjs to plugins array before svgSprites.

gotcha Vue 3 component import requires ?vueComponent query ↓

fix Use import MyIcon from './icon.svg?vueComponent' instead of bare import.

gotcha React component import requires ?jsx query ↓

fix Use import MyIcon from './icon.svg?jsx' instead of bare import.

deprecated xlink:href is deprecated in favor of href in SVG2 ↓

fix Use href="#id" instead of xlink:href="#id" in SVG use elements.

gotcha TypeScript declarations require manual type augmentation ↓

fix Add declare module '*.svg?*' declarations in a .d.ts file.

Install

npm install rollup-plugin-svg-sprites

yarn add rollup-plugin-svg-sprites

pnpm add rollup-plugin-svg-sprites

Imports

default (plugin)

wrong

const svgSprites = require('rollup-plugin-svg-sprites')

correct

import svgSprites from 'rollup-plugin-svg-sprites'

ESM-only; no default CommonJS export available.

SVG as Vue component
wrong
```
import MyIcon from './my-icon.svg'
```
correct
```
import MyIcon from './my-icon.svg?vueComponent'
```
Must use ?vueComponent query for Vue 3 SFC. Without it, returns an object with id only.
SVG as React component
wrong
```
import MyIcon from './my-icon.svg'
```
correct
```
import MyIcon from './my-icon.svg?jsx'
```
Must use ?jsx query for React JSX output. Without it, returns an object with id only.

Quickstart

Minimal setup for Rollup with SVG sprite generation, showing both basic usage and Vue 3 component import.

// rollup.config.js
import svgSprites from 'rollup-plugin-svg-sprites';
import commonjs from '@rollup/plugin-commonjs';

export default {
  input: 'src/index.js',
  output: { format: 'esm', file: 'dist/bundle.js' },
  plugins: [commonjs(), svgSprites()]
};

// src/index.js
import myIcon from './icon.svg';
console.log(myIcon.id); // e.g., 'icon'

// HTML or SVG usage:
// <svg><use xlink:href="#${myIcon.id}"></use></svg>

// For Vue 3:
// <template><MyIcon /></template>
// <script setup>
// import MyIcon from './icon.svg?vueComponent'
// </script>