@fluentui/react-icons-font-subsetting-webpack-plugin

This package includes a plugin for webpack@>=5.0.0 and @rspack/core@>=2.0.0 to subset the icon font files used by @fluentui/react-icons when using font-based icon implementations.

If optimization.usedExports is enabled (as it is by default in production mode), this plugin will subset the font files to only include the glyphs actually used by your build.

Supported Import Patterns

The plugin supports the following import patterns from @fluentui/react-icons:

1. Using the fluentIconFont condition

// Uses font implementation via resolve.conditionNames
import { AddRegular, DeleteFilled } from '@fluentui/react-icons';

2. Using atomic imports from @fluentui/react-icons/fonts/*

// Direct atomic imports - no conditionNames required
import { AddRegular, AddFilled } from '@fluentui/react-icons/fonts/add';
import { DeleteRegular } from '@fluentui/react-icons/fonts/delete';

Atomic imports provide better tree-shaking and faster build times for applications using a small number of icons.

3. Using headless atomic imports from @fluentui/react-icons/headless/fonts/*

// Headless font atoms — no Griffel runtime.
// You MUST also import the headless font CSS so the @font-face declarations and
// font files enter the module graph (the headless atoms don't import them):
import '@fluentui/react-icons/headless/fonts/styles.css';
import { AddRegular, AddFilled } from '@fluentui/react-icons/headless/fonts/add';

The plugin subsets the same shared font files used by the standard API, based on the headless icons you actually use. Because the font files arrive via styles.css, your config needs a CSS loader (e.g. css-loader) so the url(...) references resolve into webpack assets.

Tip 💡: You don't have to write atomic headless imports by hand. Pair this plugin with @fluentui/react-icons-atomic-webpack-loader using { headless: true, iconVariant: 'fonts' } — it rewrites plain barrel imports (import { AddFilled } from '@fluentui/react-icons') into headless font atoms, which this plugin then subsets. You still import @fluentui/react-icons/headless/fonts/styles.css yourself.

The plugin is query-aware for the atomic loader's moduleGranularity: 'icon' mode. Queried modules are attributed through their query-free physical paths while their exact selected exports are aggregated. Use coordinated loader/plugin releases: the two packages perform a compilation-level v1 selector capability handshake and fail the build instead of producing an incorrect subset when support is missing or incompatible.

Usage

With fluentIconFont condition

// webpack.config.js
const {
  default: FluentUIReactIconsFontSubsettingPlugin,
} = require('@fluentui/react-icons-font-subsetting-webpack-plugin');

module.exports = {
  module: {
    rules: [
      // Treat the font files as webpack assets
      {
        test: /\.(ttf|woff2?)$/,
        type: 'asset',
      },
    ],
  },
  resolve: {
    // Include 'fluentIconFont' to use the font implementation of the Fluent icons
    conditionNames: ['fluentIconFont', 'import'],
  },
  plugins: [
    // Include this plugin
    new FluentUIReactIconsFontSubsettingPlugin(),
  ],
};

With atomic imports (no conditionNames required)

// webpack.config.js
const {
  default: FluentUIReactIconsFontSubsettingPlugin,
} = require('@fluentui/react-icons-font-subsetting-webpack-plugin');

module.exports = {
  module: {
    rules: [
      // Treat the font files as webpack assets
      {
        test: /\.(ttf|woff2?)$/,
        type: 'asset',
      },
    ],
  },
  plugins: [
    // Include this plugin
    new FluentUIReactIconsFontSubsettingPlugin(),
  ],
};

With rspack

The plugin is bundler-agnostic and works unchanged in rspack — the same configuration applies:

// rspack.config.js
const {
  default: FluentUIReactIconsFontSubsettingPlugin,
} = require('@fluentui/react-icons-font-subsetting-webpack-plugin');

module.exports = {
  module: {
    rules: [
      {
        test: /\.(ttf|woff2?)$/,
        type: 'asset',
      },
    ],
  },
  plugins: [new FluentUIReactIconsFontSubsettingPlugin()],
};

Two rspack-specific notes:

• For the headless import pattern, use rspack.CssExtractRspackPlugin instead of mini-css-extract-plugin, which is not compatible with rspack.
• webpack and @rspack/core are both declared as optional peer dependencies, so you only need to install the bundler you actually use.

rspack >=2.0.0 is required because subsetting reads the module graph, and moduleGraph.getUsedExports() was exposed to the JS API in rspack 2.0.0.

On rspack 2.0.x there is one limitation: moduleGraph.getProvidedExports() only landed in 2.1.0, and it is what lets the plugin subset icons reached through a namespace import (import * as Icons from '@fluentui/react-icons/fonts/…'). Because those icons cannot be identified, every font in the affected package is left un-subset — not just the namespace import's own module — since subsetting from the package's remaining imports would drop glyphs the namespace import actually uses. A build warning names the package when this happens. Named imports — the common case — are unaffected and subset fully. Upgrade to rspack >=2.1.0 for complete coverage.

Options

onDuplicateInstances

'warn' | 'error', default 'warn'.

The plugin subsets against one resolved @fluentui/react-icons package instance. When font modules resolve from more than one installed copy — peer-dependency variants in a virtual store will do this without any version conflict — emitted font assets cannot be attributed safely to one coherent source.

The plugin detects multiple participating copies before inspecting font-asset ownership, leaves all fonts un-subset so every glyph still renders, and warns with the paths involved. Set 'error' to fail the build instead:

new FluentUIReactIconsFontSubsettingPlugin({ onDuplicateInstances: 'error' });

To get subsetting back, collapse the copies onto one instance with bundler resolve.alias entries. Note that this also binds every copy to a single React and Griffel instance.

Using ESM import and CommonJS require() from the same installation does not count as two copies. Their used exports are combined, and each emitted font asset is subset once.

Development Checks

Run yarn nx run react-icons-font-subsetting-webpack-plugin:test for unit, type, and webpack/rspack integration coverage.

Run yarn nx run react-icons-font-subsetting-webpack-plugin:test:render for the localized full/subset font browser check. It requires Playwright Chromium (yarn playwright install chromium) and checks standard/headless rendering, LTR/RTL contexts, and desktop/mobile viewports. Screenshots are written to tmp/localized-font-render at the repository root.