iconfont-webpack-plugin

5.0.1 verified Sat Apr 25 auth: no javascript

Webpack plugin that simplifies icon font usage by allowing inline SVG references in CSS via the `font-icon` property. It converts SVGs into webfonts during the build, supporting all CSS preprocessors (Sass, Less, Stylus, PostCSS, vanilla CSS). Current stable version is 5.0.1, compatible with webpack >=3. Key differentiator: eliminates manual icon font generation tools; works seamlessly with webpack's resolve and PostCSS. Caveat: requires postcss-loader and css-loader as peer dependencies (v2+ and v4+ respectively).

Common errors

error Error: PostCSS plugin iconfont-webpack-plugin requires postcssOptions ↓

cause Missing `postcssOptions` configuration in webpack rule for postcss-loader.

fix

Ensure postcss-loader is configured with a postcssOptions function returning plugins array containing IconfontWebpackPlugin.

error Error: Cannot find module 'postcss-loader' ↓

cause Missing required peer dependency postcss-loader.

fix

Install postcss-loader: npm install --save-dev postcss-loader

error Error: 'font-icon' property is not allowed in CSS ↓

cause CSS not processed by the plugin, or plugin not correctly configured.

fix

Verify that CSS files are processed by postcss-loader with this plugin as a PostCSS plugin.

Warnings

error ⚠️ This plugin requires webpack's resolve function passed from loader context. Failing to pass `resolve` will cause build errors. ↓

fix Ensure you pass `resolve: loader.resolve` in the PostCSS plugin options.

gotcha SVG files must have all fills/colors removed before conversion. The plugin does not strip them automatically. ↓

fix Preprocess SVGs to remove fill and stroke attributes, or ensure they use black fill only.

gotcha The `font-icon` property is non-standard CSS. It will not work without this plugin processing the CSS. ↓

fix Always run CSS through postcss-loader with this plugin.

error ⚠️ Breaking: In v5, the plugin no longer includes postcss-loader in its own dependencies. You must install `postcss-loader` and `css-loader` separately. ↓

fix Run `npm install --save-dev postcss-loader css-loader` in your project.

Install

npm install iconfont-webpack-plugin

yarn add iconfont-webpack-plugin

pnpm add iconfont-webpack-plugin

Imports

IconfontWebpackPlugin

wrong

import IconfontWebpackPlugin from 'iconfont-webpack-plugin';

correct

const IconfontWebpackPlugin = require('iconfont-webpack-plugin');

The package does not ship ESM; use CommonJS require.

Quickstart

Setup webpack config with IconfontWebpackPlugin and use font-icon in CSS to inline SVGs as icon font.

// webpack.config.js
const IconfontWebpackPlugin = require('iconfont-webpack-plugin');

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: [
          'css-loader',
          {
            loader: 'postcss-loader',
            options: {
              postcssOptions: (loader) => ({
                plugins: [
                  new IconfontWebpackPlugin({
                    resolve: loader.resolve
                  })
                ]
              })
            }
          }
        ]
      }
    ]
  }
};

/* style.css */
a:before {
  font-icon: url('./account.svg');
}