webpack-svgstore-plugin

4.1.0 verified Sat Apr 25 auth: no javascript

Webpack plugin that generates SVG sprites (SVG store) from a set of SVG files. Version 4.1.0 is the latest stable release. Use v3.x for Webpack 1.x and v4.x for Webpack 2.x. It integrates svgo for optimization, supports prefixing for icon IDs, and includes an optional built-in AJAX sprite loader. Key differentiator: it uses magic variables like `__svg__` in source files to declare input glob and output filename, which can be confusing for newcomers.

Common errors

error Error: Cannot find module 'webpack-svgstore-plugin' ↓

cause Package not installed or incorrect import path.

fix

Run npm install webpack-svgstore-plugin --save-dev and use require('webpack-svgstore-plugin').

error TypeError: SvgStore is not a constructor ↓

cause Using ESM import instead of CommonJS require.

fix

Replace import SvgStore from 'webpack-svgstore-plugin' with const SvgStore = require('webpack-svgstore-plugin').

error Error: webpack-svgstore-plugin requires webpack@2.x.x (for v4) or webpack@1.x.x (for v3) ↓

cause Installed plugin version does not match webpack version.

fix

Match versions: npm install webpack-svgstore-plugin@3 --save-dev for webpack 1.x, or @4 for webpack 2.x.

Warnings

breaking Webpack version mismatch: use v3.x for Webpack 1.x, v4.x for Webpack 2.x. ↓

fix Install webpack-svgstore-plugin@3.x if using Webpack 1.x, or @4.x for Webpack 2.x.

gotcha Magic variable `__svg__` must be declared as a global-like variable in source code, which can be missed by linters or minifiers. ↓

fix Ensure the variable is declared and not tree-shaken. Use the exact pattern shown in docs.

deprecated Node.js 0.12 is no longer supported. Minimum Node 4.0+ required. ↓

fix Upgrade Node.js to version 4.0+ (recommended 7.0+).

gotcha The built-in AJAX sprite loader (`svgxhr`) must be explicitly required; it is not loaded automatically. ↓

fix Add `require('webpack-svgstore-plugin/src/helpers/svgxhr')(__svg__);` in your entry file.

gotcha Sprite filename pattern uses `[hash]` placeholder which resolves to content hash of the sprite, not a build hash. ↓

fix Use `[hash]` as documented; ensure output path is correct.

Install

npm install webpack-svgstore-plugin

yarn add webpack-svgstore-plugin

pnpm add webpack-svgstore-plugin

Imports

SvgStore
wrong
```
import SvgStore from 'webpack-svgstore-plugin';
```
correct
```
const SvgStore = require('webpack-svgstore-plugin');
```
This package does not ship ESM; CommonJS require is required. No default export exists for ESM.

svgoOptions

wrong

new SvgStore({ svgo: { removeTitle: true } })

correct

new SvgStore({ svgoOptions: { plugins: [{ removeTitle: true }] } })

Options are passed under the 'svgoOptions' key, not directly under 'svgo'.

prefix

wrong

new SvgStore({ namePrefix: 'icon' })

correct

new SvgStore({ prefix: 'icon' })

Prefix key is 'prefix', not 'namePrefix'.

Quickstart

Shows how to configure the plugin in webpack config, declare the sprite definition in source, and use the sprite in HTML.

// webpack.config.js
var SvgStore = require('webpack-svgstore-plugin');

module.exports = {
  entry: './src/index.js',
  output: {
    path: __dirname + '/dist',
    filename: 'bundle.js'
  },
  plugins: [
    new SvgStore({
      svgoOptions: {
        plugins: [
          { removeTitle: true }
        ]
      },
      prefix: 'icon'
    })
  ]
};

// In your source file (e.g., src/index.js):
var __svg__ = { path: './assets/svg/**/*.svg', name: 'assets/svg/[hash].logos.svg' };
require('webpack-svgstore-plugin/src/helpers/svgxhr')(__svg__);

// Then in HTML:
<svg class="svg-icon">
  <use xlink:href="#icon-name"></use>
</svg>