svg-sprite-html-webpack

2.4.1 verified Sat Apr 25 auth: no javascript maintenance

Webpack loader and plugin that generates an SVG sprite with <symbol> elements and injects it directly into the HTML output from html-webpack-plugin. Version 2.4.1 supports Webpack v3, v4, and v5 (added by contributors) and html-webpack-plugin v2, v3, and v5. The package is no longer actively maintained by the original author but has community upkeep. Unlike runtime SVG sprite solutions, this avoids extra HTTP requests by embedding the sprite at compile time. SVG files imported in JavaScript or specified via includeFiles are automatically optimized and deduplicated based on content.

Common errors

error Module not found: Error: Can't resolve 'svg-sprite-html-webpack' ↓

cause Package not installed or missing from node_modules.

fix

Run 'npm install svg-sprite-html-webpack --save-dev' to install the package.

error Error: The plugin 'SvgSpriteHtmlWebpackPlugin' must be placed after 'HtmlWebpackPlugin' in plugins array ↓

cause Plugin order incorrect in webpack config.

fix

Reorder plugins so HtmlWebpackPlugin comes before SvgSpriteHtmlWebpackPlugin.

error TypeError: SvgSpriteHtmlWebpackPlugin.getLoader is not a function ↓

cause Incorrect import; likely using default import of the class instead of the exported object.

fix

Use 'const SvgSpriteHtmlWebpackPlugin = require("svg-sprite-html-webpack");' correctly.

Warnings

gotcha Since Webpack 4, SvgSpriteHtmlWebpackPlugin must be declared after HtmlWebpackPlugin in the plugins array. ↓

fix Ensure new SvgSpriteHtmlWebpackPlugin() is placed after new HtmlWebpackPlugin() in the plugins array.

breaking In Webpack 5 and html-webpack-plugin v5, there may be compatibility issues; the plugin is not officially maintained for v5 after v2.4.0. ↓

fix If using Webpack 5, test thoroughly. Consider alternative plugins like 'svg-sprite-loader' or 'svg-inline-loader' if issues arise.

deprecated The package is no longer actively maintained by the original author; functionality is provided by community contributions. ↓

fix For long-term projects, evaluate alternative solutions with active maintenance.

gotcha When using includeFiles option, files with identical content are deduplicated (only one injected even if different filenames). ↓

fix Use generateSymbolId if you need unique symbols for duplicate content files.

breaking The loader (getLoader()) must be used in the module rules; using the package as a plain loader string will fail. ↓

fix Always call SvgSpriteHtmlWebpackPlugin.getLoader() to get the loader configuration.

Install

npm install svg-sprite-html-webpack

yarn add svg-sprite-html-webpack

pnpm add svg-sprite-html-webpack

Imports

SvgSpriteHtmlWebpackPlugin
wrong
```
import SvgSpriteHtmlWebpackPlugin from 'svg-sprite-html-webpack';
```
correct
```
const SvgSpriteHtmlWebpackPlugin = require('svg-sprite-html-webpack');
```
Package exports a single class via module.exports; ESM import only works with default import if using bundler that supports interop, but CJS require is safest.
getLoader
wrong
```
use: 'svg-sprite-html-webpack'
```
correct
```
use: SvgSpriteHtmlWebpackPlugin.getLoader()
```
Must call the static getLoader() method to obtain the loader configuration object.
svg import (e.g., import checkmark from './icon.svg')
wrong
```
const checkmark = require('./icons/checkmark.svg');
```
correct
```
import checkmark from './icons/checkmark.svg';
```
When using the loader, SVG files export the symbol ID as a string. If using CommonJS require, the value is the default export of the loader module.
HtmlWebpackPlugin
```
const HtmlWebpackPlugin = require('html-webpack-plugin');
```
HtmlWebpackPlugin is a separate peer dependency and must be required before SvgSpriteHtmlWebpackPlugin in the plugins array.

Quickstart

Minimal webpack config that processes SVG files via the loader and injects the sprite into the HTML page via the plugin.

const HtmlWebpackPlugin = require('html-webpack-plugin');
const SvgSpriteHtmlWebpackPlugin = require('svg-sprite-html-webpack');

module.exports = {
  entry: './src/index.js',
  output: { path: __dirname + '/dist', filename: 'bundle.js' },
  module: {
    rules: [{
      test: /\.svg$/,
      exclude: /node_modules/,
      use: SvgSpriteHtmlWebpackPlugin.getLoader()
    }]
  },
  plugins: [
    new HtmlWebpackPlugin({ filename: 'index.html', template: 'template.html' }),
    new SvgSpriteHtmlWebpackPlugin()
  ]
};