html-webpack-inline-svg-plugin

2.3.0 verified Sat Apr 25 auth: no javascript

Webpack plugin (v2.3.0) that converts <img inline src='...svg'> tags in HTML templates into inlined <svg> elements after processing by html-webpack-plugin. Uses SVGO for optimization. Key differentiator: works alongside other loaders, supports deep nesting, URLs, and webpack aliases. Release cadence: ~1 major per year. Requires html-webpack-plugin (v4+) and webpack 4/5.

Common errors

error Error: HtmlWebpackInlineSVGPlugin: svgoConfig should be passed inside the plugin constructor, not in HtmlWebpackPlugin options. ↓

cause svgoConfig placed incorrectly in HtmlWebpackPlugin options as per v2.3.0 breaking change.

fix

Move svgoConfig to new HtmlWebpackInlineSVGPlugin({ svgoConfig: ... }) and remove from HtmlWebpackPlugin options.

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

cause Missing peer dependency html-webpack-plugin.

fix

Install it: npm install --save-dev html-webpack-plugin

error Module not found: Error: Can't resolve 'icon.svg' ↓

cause SVG file path is incorrect or webpack cannot resolve it. Plugin does not resolve paths itself; relies on webpack loaders or absolute/relative paths.

fix

Use correct path relative to output directory or configure a loader like file-loader. Ensure runPreEmit is set correctly.

Warnings

breaking svgoConfig option moved from HtmlWebpackPlugin to HtmlWebpackInlineSVGPlugin constructor ↓

fix Move svgoConfig into new HtmlWebpackInlineSVGPlugin({ svgoConfig: ... }). Do NOT pass it to HtmlWebpackPlugin.

breaking Default behavior changed: plugin now processes SVGs after files are written to output directory (post-emit). Prior to 1.0.0 it ran pre-emit. ↓

fix If you rely on pre-emit behavior, set runPreEmit: true in plugin options. Update SVG src paths to be relative to output directory.

gotcha Plugin only processes <img> tags with inline attribute and .svg extension. Tags without inline or with non-.svg src are ignored silently. ↓

fix Ensure <img> tag includes inline attribute and src points to .svg file. PNG, JPG, etc. are ignored.

gotcha Webpack aliases require loaders to resolve SVG paths. If using alias, you must configure file-loader/url-loader and ensure templates are parsed (e.g., with html-loader). ↓

fix Install file-loader and html-loader. Set html-loader options to handle attributes (e.g., attrs=['img:src']). See plugin docs for configuration.

Install

npm install html-webpack-inline-svg-plugin

yarn add html-webpack-inline-svg-plugin

pnpm add html-webpack-inline-svg-plugin

Imports

HtmlWebpackInlineSVGPlugin

wrong

import HtmlWebpackInlineSVGPlugin from 'html-webpack-inline-svg-plugin';

correct

const HtmlWebpackInlineSVGPlugin = require('html-webpack-inline-svg-plugin');

Plugin is CJS-only; no ESM export. Use require() in webpack config file.

HtmlWebpackPlugin

wrong

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

correct

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

Do not confuse with this plugin; html-webpack-plugin is a separate required dependency.

svgoConfig
wrong
```
new HtmlWebpackPlugin({ svgoConfig: { ... } })
```
correct
```
new HtmlWebpackInlineSVGPlugin({ svgoConfig: { plugins: ['removeDoctype'] } })
```
Breaking change in v2.3.0: svgoConfig must be passed to HtmlWebpackInlineSVGPlugin, not HtmlWebpackPlugin. An error is thrown if placed incorrectly.

Quickstart

Webpack config with html-webpack-plugin and html-webpack-inline-svg-plugin, setting SVGO options and runPreEmit flag.

const HtmlWebpackPlugin = require('html-webpack-plugin');
const HtmlWebpackInlineSVGPlugin = require('html-webpack-inline-svg-plugin');

module.exports = {
  entry: './src/index.js',
  plugins: [
    new HtmlWebpackPlugin({
      template: './src/index.html'
    }),
    new HtmlWebpackInlineSVGPlugin({
      svgoConfig: {
        plugins: [
          { name: 'removeViewBox', active: false }
        ]
      },
      runPreEmit: false
    })
  ]
};

// In your HTML template:
// <img inline src="icon.svg"> becomes the <svg> content