rollup-plugin-svg-sprite

1.0.0 verified Mon Apr 27 auth: no javascript

Rollup plugin to extract SVG imports from your bundle and generate an external SVG sprite file, with optional optimization via SVGO. Current stable version is 1.0.0. Released on a low cadence. Key differentiators: native Rollup integration using generateBundle hook, support for SVGO optimization, minification enabled by default, and tests with 100% code coverage. Alternative to webpack-based solutions like svg-sprite-loader.

Common errors

error TypeError: svgSprite is not a function ↓

cause Using require() instead of import, or importing from wrong path.

fix

Use import svgSprite from 'rollup-plugin-svg-sprite' in an ES module context.

error Error: Plugin error: Cannot find module 'rollup-plugin-svg-sprite' ↓

cause The package is not installed in your project's node_modules.

fix

Run npm install rollup-plugin-svg-sprite --save-dev or yarn add rollup-plugin-svg-sprite --dev.

error Error: outputFolder is required ↓

cause Missing required `outputFolder` option in the plugin configuration.

fix

Provide an outputFolder string, e.g., svgSprite({ outputFolder: 'dist/public' }).

Warnings

breaking v1.0.0 removes the `prettify` option. The sprite is minified by default; use `minify` to control. ↓

fix Replace `prettify: true/false` with `minify: false` if you need unminified sprite.

breaking v1.0.0 drops Node 6 support. Requires Node >=8.3. ↓

fix Upgrade Node to version 8.3 or higher.

breaking v0.3.0 replaces deprecated `onwrite` hook with `generateBundle`. Using older version with Rollup >=1.0.0 fails. ↓

fix Upgrade plugin to v0.3.0+ and use the new `generateBundle` hook.

breaking v0.3.0 sets rollup peer dependency to >=1.0.0. Incompatible with Rollup <1.0.0. ↓

fix Upgrade Rollup to 1.0.0 or later, and plugin to v0.3.0+.

gotcha The plugin only generates the sprite file; it does not inject a reference into your bundle. You must manually include the sprite in your HTML. ↓

fix Add a <script> or <link> to the generated sprite file in your HTML, or use a loader that injects it automatically.

Install

npm install rollup-plugin-svg-sprite

yarn add rollup-plugin-svg-sprite

pnpm add rollup-plugin-svg-sprite

Imports

default

wrong

const svgSprite = require('rollup-plugin-svg-sprite')

correct

import svgSprite from 'rollup-plugin-svg-sprite'

ESM only. CommonJS require is not supported for this ES module.

svgSprite as function call in config
wrong
```
new svgSprite({ outputFolder: 'dist/public' })
```
correct
```
svgSprite({ outputFolder: 'dist/public' })
```
The export is a function, not a class. Do not use `new`.
Rollup configuration import
wrong
```
import svgSprite from 'rollup-plugin-svg-sprite/dist/index.js'
```
correct
```
import svgSprite from 'rollup-plugin-svg-sprite'
```
The package exports a single function from the main entry. Subpath imports are not needed.

Quickstart

Rollup config using rollup-plugin-svg-sprite to generate an external SVG sprite from imported SVGs.

// rollup.config.js
import svgSprite from 'rollup-plugin-svg-sprite'

export default {
  input: 'src/index.js',
  output: {
    file: 'dist/bundle.js',
    format: 'iife'
  },
  plugins: [
    svgSprite({
      outputFolder: 'dist/public'
    })
  ]
}

// Then in your source files:
import './svg/icon1.svg'
import './svg/icon2.svg'