@fluentui/react-icons-font-subsetting-webpack-plugin 2.0.317 → 2.0.319

package/README.md

@@ -1,33 +1,82 @@
-@fluentui/react-icons-font-subsetting-webpack-plugin
-===
+# @fluentui/react-icons-font-subsetting-webpack-plugin
 
-This package includes a plugin for `webpack@>=5.0.0` to subset the icon font files used by `@fluentui/react-icons` when using the `"fluentIconFont"` condition in `resolve.conditionNames`. 
+This package includes a plugin for `webpack@>=5.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), this plugin will subset the font files to only include the glyphs actually used by your build.
+If `optimization.usedExports` is enabled (as it is by default in webpack `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
+
+```js
+// Uses font implementation via resolve.conditionNames
+import { AddRegular, DeleteFilled } from '@fluentui/react-icons';
+```
+
+### 2. Using atomic imports from `@fluentui/react-icons/fonts/*`
+
+```js
+// 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.
+
+## Usage
+
+### With `fluentIconFont` condition
+
+```js
+// 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)
 
-Usage
----
 ```js
 // webpack.config.js
-const {default: FluentUIReactIconsFontSubsettingPlugin} = require('@fluentui/react-icons-font-subsetting-webpack-plugin');
+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(),
+  module: {
+    rules: [
+      // Treat the font files as webpack assets
+      {
+        test: /\.(ttf|woff2?)$/,
+        type: 'asset',
+      },
     ],
+  },
+  plugins: [
+    // Include this plugin
+    new FluentUIReactIconsFontSubsettingPlugin(),
+  ],
 };
-```
+```

package/lib/index.d.ts

@@ -1,4 +1,17 @@
-import * as webpack from "webpack";
+import * as webpack from 'webpack';
 export default class FluentUIReactIconsFontSubsettingPlugin implements webpack.WebpackPluginInstance {
+    /**
+     * Entry point for the Webpack plugin that registers hooks to perform font subsetting for `@fluentui/react-icons`.
+     *
+     * This method is executed **once** by Webpack when the plugin is initialized during the compiler's
+     * bootstrap phase. The internal logic hooked into `optimizeAssets` is executed **once per compilation**
+     * (whenever Webpack processes the module graph and prepares to output assets) during the
+     * asset optimization stage.
+     *
+     * It analyzes the module graph to determine which specific icons are used from Fluent UI icon packages
+     * and triggers font subsetting to remove unused glyphs from the final output assets.
+     *
+     * @param compiler - The Webpack compiler instance.
+     */
     apply(compiler: webpack.Compiler): void;
 }

package/lib/index.js

@@ -30,19 +30,34 @@ const webpack = __importStar(require("webpack"));
 const subset_font_1 = __importDefault(require("subset-font"));
 const path_1 = require("path");
 const promises_1 = require("fs/promises");
-const PLUGIN_NAME = "FluentUIReactIconsFontSubsettingPlugin";
+const PLUGIN_NAME = 'FluentUIReactIconsFontSubsettingPlugin';
 const FONT_FILES_BASE_NAMES = [
-    "FluentSystemIcons-Filled",
-    "FluentSystemIcons-Resizable",
-    "FluentSystemIcons-Regular",
-    "FluentSystemIcons-Light"
-];
-const FONT_EXTENSIONS = [
-    '.ttf',
-    '.woff',
-    '.woff2'
+    'FluentSystemIcons-Filled',
+    'FluentSystemIcons-Resizable',
+    'FluentSystemIcons-Regular',
+    'FluentSystemIcons-Light',
 ];
+const FONT_EXTENSIONS = ['.ttf', '.woff', '.woff2'];
+/**
+ *  Match both chunk files and atomic font imports:
+ *  - lib/fonts/sizedIcons/chunk-0.js (chunk-based)
+ *  - lib/atoms/fonts/access-time.js (atomic imports)
+ */
+const REACT_ICONS_FONT_MODULE_IMPORT_PATTERN = /react-icons[\/\\]lib(-cjs)?[\/\\](fonts[\/\\](sizedIcons|icons)[\/\\]chunk-\d+|atoms[\/\\]fonts[\/\\][\w-]+)\.js$/;
 class FluentUIReactIconsFontSubsettingPlugin {
+    /**
+     * Entry point for the Webpack plugin that registers hooks to perform font subsetting for `@fluentui/react-icons`.
+     *
+     * This method is executed **once** by Webpack when the plugin is initialized during the compiler's
+     * bootstrap phase. The internal logic hooked into `optimizeAssets` is executed **once per compilation**
+     * (whenever Webpack processes the module graph and prepares to output assets) during the
+     * asset optimization stage.
+     *
+     * It analyzes the module graph to determine which specific icons are used from Fluent UI icon packages
+     * and triggers font subsetting to remove unused glyphs from the final output assets.
+     *
+     * @param compiler - The Webpack compiler instance.
+     */
     apply(compiler) {
         compiler.hooks.compilation.tap(PLUGIN_NAME, (compilation) => {
             compilation.hooks.optimizeAssets.tapPromise(PLUGIN_NAME, async () => {
@@ -51,8 +66,11 @@ class FluentUIReactIconsFontSubsettingPlugin {
                 for (const m of compilation.modules) {
                     if (isFluentUIReactFontChunk(m)) {
                         const usedModuleExports = compilation.moduleGraph.getUsedExports(m, undefined);
+                        // Either all exports are used or there's no info on used exports
                         if (usedModuleExports === null || typeof usedModuleExports === 'boolean') {
-                            // Either all exports are used or there's no info on used exports
+                            // In development mode (or when optimization.usedExports is disabled),
+                            // getUsedExports() returns `true` (all exports used) or `null` (no info).
+                            // Subsetting requires knowing exactly which exports are used.
                             continue;
                         }
                         const pkgLibPath = (0, path_1.resolve)((0, path_1.dirname)(m.resource), '../..');
@@ -69,19 +87,24 @@ class FluentUIReactIconsFontSubsettingPlugin {
                         optimizationPromises.push(optimizeFontAsset(codepointMap, usedExports, compilation, assetName));
                     }
                 }
-                await optimizationPromises;
+                // IMPORTANT: actually await all subsetting work
+                await Promise.all(optimizationPromises);
             });
         });
     }
 }
 exports.default = FluentUIReactIconsFontSubsettingPlugin;
 async function optimizeFontAsset(codepointMap, usedExports, compilation, assetName) {
-    const subsetText = Object.entries(codepointMap)
-        .filter(([glyphName]) => usedExports.has(glyphName))
-        .map(([, codepoint]) => String.fromCodePoint(codepoint))
-        .join('');
+    // Build subset text from the used exports set (usually small) instead of scanning all glyphs
+    let subsetText = '';
+    for (const glyphName of usedExports) {
+        const codepoint = codepointMap[glyphName];
+        if (codepoint !== undefined) {
+            subsetText += String.fromCodePoint(codepoint);
+        }
+    }
     let source = compilation.assets[assetName].source();
-    if (typeof source === "string") {
+    if (typeof source === 'string') {
         source = Buffer.from(source);
     }
     compilation.assets[assetName] = new webpack.sources.RawSource(await (0, subset_font_1.default)(source, subsetText, {
@@ -90,27 +113,38 @@ async function optimizeFontAsset(codepointMap, usedExports, compilation, assetNa
 }
 function getTargetFormat(assetName) {
     switch ((0, path_1.extname)(assetName)) {
-        case ".woff":
-            return "woff";
-        case ".woff2":
-            return "woff2";
+        case '.woff':
+            return 'woff';
+        case '.woff2':
+            return 'woff2';
         default:
-            return "sfnt";
+            return 'sfnt';
     }
 }
 function isNormalModule(m) {
     return m instanceof webpack.NormalModule;
 }
 function isFluentUIReactFontChunk(m) {
-    if (isNormalModule(m)) {
-        return /react-icons[\/\\]lib(-cjs)?[\/\\]fonts[\/\\](sizedIcons|icons)[\/\\]chunk-\d+\.js$/.test(m.resource);
+    if (!isNormalModule(m)) {
+        return false;
+    }
+    const resource = m.resource;
+    if (!resource) {
+        return false;
+    }
+    // Cheap pre-filter before regex
+    if (!resource.includes('react-icons')) {
+        return false;
     }
-    return false;
+    return REACT_ICONS_FONT_MODULE_IMPORT_PATTERN.test(resource);
 }
 async function getFontAssetsAndCodepoints(pkgLibPath, compilation) {
     const utilsFontsFolder = (0, path_1.resolve)(pkgLibPath, 'utils/fonts');
-    const codepoints = Object.fromEntries(await Promise.all(FONT_FILES_BASE_NAMES.map(async (fontBaseName) => [fontBaseName, JSON.parse(await (0, promises_1.readFile)((0, path_1.resolve)(utilsFontsFolder, `${fontBaseName}.json`), 'utf8'))])));
-    const fontPaths = new Map(FONT_FILES_BASE_NAMES.flatMap(fontBaseName => FONT_EXTENSIONS.map(ext => [(0, path_1.resolve)(utilsFontsFolder, `${fontBaseName}${ext}`), codepoints[fontBaseName]])));
+    const codepoints = Object.fromEntries(await Promise.all(FONT_FILES_BASE_NAMES.map(async (fontBaseName) => [
+        fontBaseName,
+        JSON.parse(await (0, promises_1.readFile)((0, path_1.resolve)(utilsFontsFolder, `${fontBaseName}.json`), 'utf8')),
+    ])));
+    const fontPaths = new Map(FONT_FILES_BASE_NAMES.flatMap((fontBaseName) => FONT_EXTENSIONS.map((ext) => [(0, path_1.resolve)(utilsFontsFolder, `${fontBaseName}${ext}`), codepoints[fontBaseName]])));
     const result = [];
     for (const m of compilation.modules) {
         if (isNormalModule(m) && fontPaths.has(m.resource)) {

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@fluentui/react-icons-font-subsetting-webpack-plugin",
-  "version": "2.0.317",
+  "version": "2.0.319",
   "description": "Webpack plugin to subset the icon fonts used by @fluentui/react-icons based on which icons are used.",
   "main": "lib/index.js",
   "scripts": {
     "test": "webpack -c test/webpack.config.js",
+    "dev": "webpack serve -c test/webpack.config.js --open",
     "build": "tsc -p ."
   },
   "engines": {
@@ -36,4 +37,4 @@
   "files": [
     "lib/*"
   ]
-}
+}