rollup-plugin-svg-to-symbol

1.0.0 verified Mon Apr 27 auth: no javascript

A Rollup plugin that transforms SVG files into symbol strings, enabling custom sprite generation. Version 1.0.0 is the current stable release. It focuses solely on converting SVGs to `<symbol>` elements with optional SVGO optimization and custom ID extraction. Unlike broader SVG loading plugins, it outputs raw symbol markup for manual assembly into sprites. Minimal dependencies, easy to configure.

Common errors

error Error: The plugin "svg-to-symbol" doesn't support changing the order of its hooks. ↓

cause Misconfigured plugin order after other transform plugins.

fix

Place svgToSymbol() after other SVG-loading plugins but before any bundling.

error Cannot find module 'svgo' ↓

cause svgo is not installed when custom SVGO options are provided.

fix

Install svgo as a dev dependency: npm i svgo -D.

Warnings

gotcha Default symbol ID uses only the filename without extension, which may cause collisions across directories. ↓

fix Provide extractId option with filePath to ensure uniqueness.

deprecated Option 'svgo' expects an object, but if set to false, SVGO optimization is disabled. Type checking may fail. ↓

fix Set svgo to {} for default or { plugins: [] } to disable; avoid non-object values.

gotcha The plugin does not emit any CSS or assets; it only transforms imports. If you expect a file output, use with other plugins. ↓

fix Combine with rollup-plugin-copy or similar to output sprite files.

Install

npm install rollup-plugin-svg-to-symbol

yarn add rollup-plugin-svg-to-symbol

pnpm add rollup-plugin-svg-to-symbol

Imports

default

wrong

const svgToSymbol = require('rollup-plugin-svg-to-symbol')

correct

import svgToSymbol from 'rollup-plugin-svg-to-symbol'

ESM import is preferred; CJS require works but may need default destructuring.

plugin function

wrong

import { svgToSymbol } from 'rollup-plugin-svg-to-symbol'

correct

import svgToSymbol from 'rollup-plugin-svg-to-symbol'

The module exports a single function as default, not a named export.

SVG import
wrong
```
import { icon } from './icon.svg'
```
correct
```
import icon from './icon.svg'
```
Each SVG file is imported as a default export (string containing <symbol>).

Quickstart

Shows basic setup: configure Rollup plugin and import SVG as symbol string.

// rollup.config.js
import svgToSymbol from 'rollup-plugin-svg-to-symbol';
export default {
  input: 'src/index.js',
  output: { dir: 'dist', format: 'esm' },
  plugins: [
    svgToSymbol()
  ]
};

// src/index.js
import add from './icons/add.svg';
const sprite = `<svg>${add}</svg>`;
export default sprite;