@fluentui/react-icons-atomic-webpack-loader 0.0.1

package/README.md

@@ -0,0 +1,121 @@
+# @fluentui/react-icons-atomic-webpack-loader
+
+> **⚠️ 0.x** — this package is in early development and follows [zero-based major semver](https://0ver.org/).
+> Breaking changes may occur in minor releases until 1.0.
+
+Webpack loader that transforms barrel imports and re-exports from `@fluentui/react-icons` into atomic deep paths for better tree-shaking and smaller bundles.
+
+## Before / After
+
+```js
+// Before — barrel import pulls in the entire icon set
+import { AddFilled, bundleIcon, useIconContext } from '@fluentui/react-icons';
+export { ArrowLeftRegular } from '@fluentui/react-icons';
+
+// After — each reference resolves to a small, isolated module
+import { AddFilled } from '@fluentui/react-icons/svg/add';
+import { bundleIcon } from '@fluentui/react-icons/utils';
+import { useIconContext } from '@fluentui/react-icons/providers';
+export { ArrowLeftRegular } from '@fluentui/react-icons/svg/arrow-left';
+```
+
+## Usage
+
+Add the loader to your webpack config as an [`enforce: 'pre'`](https://webpack.js.org/configuration/module/#ruleenforce) rule so it runs on the original source before any other loaders:
+
+NOTE: Unlike most loaders, this one should NOT exclude `node_modules`. It needs to process files inside `node_modules` as well to transform barrel imports from `@fluentui/react-icons` in your third-party dependencies. Files that don't reference `@fluentui/react-icons` are skipped via a fast regex pre-check, so there is no meaningful overhead.
+
+```js
+// webpack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.[mc]?[jt]sx?$/,
+        enforce: 'pre',
+        use: ['@fluentui/react-icons-atomic-webpack-loader'],
+      },
+      // … your other rules (babel-loader, ts-loader, etc.)
+    ],
+  },
+};
+```
+
+If your existing rules exclude `node_modules`, add a separate rule to cover dependencies:
+
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.[mc]?[jt]sx?$/,
+        include: /[\\/]node_modules[\\/]/,
+        enforce: 'pre',
+        use: ['@fluentui/react-icons-atomic-webpack-loader'],
+      },
+      // … your other rules (babel-loader, ts-loader, etc.)
+    ],
+  },
+};
+```
+
+## Options
+
+| Option        | Type                                   | Default | Description                                                        |
+| ------------- | -------------------------------------- | ------- | ------------------------------------------------------------------ |
+| `iconVariant` | `'svg'` \| `'fonts'` \| `'svg-sprite'` | `'svg'` | Whether icons resolve to SVG, font-based, or SVG sprite components |
+
+### Using font icons
+
+```js
+{
+  test: /\.[mc]?[jt]sx?$/,
+  enforce: 'pre',
+  use: [
+    {
+      loader: '@fluentui/react-icons-atomic-webpack-loader',
+      options: {
+        iconVariant: 'fonts',
+      },
+    },
+  ],
+}
+```
+
+This changes icon resolution from `@fluentui/react-icons/svg/*` to `@fluentui/react-icons/fonts/*`. Non-icon exports (`utils`, `providers`) are unaffected.
+
+### Using SVG sprite icons
+
+```js
+{
+  test: /\.[mc]?[jt]sx?$/,
+  enforce: 'pre',
+  use: [
+    {
+      loader: '@fluentui/react-icons-atomic-webpack-loader',
+      options: {
+        iconVariant: 'svg-sprite',
+      },
+    },
+  ],
+}
+```
+
+This changes icon resolution from `@fluentui/react-icons/svg/*` to `@fluentui/react-icons/svg-sprite/*`. Non-icon exports (`utils`, `providers`) are unaffected.
+
+## How it works
+
+The loader uses a Babel transform to rewrite import and re-export declarations that reference `@fluentui/react-icons`. Each named specifier is routed to an atomic subpath based on its name:
+
+| Export type    | Example                                          | Resolved path                                                        |
+| -------------- | ------------------------------------------------ | -------------------------------------------------------------------- |
+| Icon component | `AddFilled`, `ArrowLeftRegular`                  | `@fluentui/react-icons/svg/add` (or `/fonts/add`, `/svg-sprite/add`) |
+| Context / hook | `useIconContext`, `IconDirectionContextProvider` | `@fluentui/react-icons/providers`                                    |
+| Utility        | `bundleIcon`, `createFluentIcon`                 | `@fluentui/react-icons/utils`                                        |
+
+Files that don't reference `@fluentui/react-icons` are passed through untouched (fast regex pre-check).
+
+## Requirements
+
+- `webpack` >= 5
+- `@fluentui/react-icons` >= 2 (with atomic subpath exports)

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+import type { LoaderContext } from 'webpack';
+export interface FluentIconsAtomicImportLoaderOptions {
+    iconVariant?: 'svg' | 'fonts' | 'svg-sprite';
+}
+export default function fluentIconsAtomicImportLoader(this: LoaderContext<FluentIconsAtomicImportLoaderOptions>, sourceCode: string): void;

package/lib/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const transform_1 = require("./transform");
+function fluentIconsAtomicImportLoader(sourceCode) {
+    const { resourcePath } = this;
+    if (!sourceCode.includes('@fluentui/react-icons')) {
+        return this.callback(null, sourceCode);
+    }
+    const { iconVariant = 'svg' } = this.getOptions();
+    try {
+        const { code, map } = (0, transform_1.transformSource)(sourceCode, { iconVariant, path: resourcePath });
+        return this.callback(null, code, map);
+    }
+    catch {
+        return this.callback(new Error(`FluentIconsAtomicImportLoader: Failed to transform "${resourcePath}"`));
+    }
+}
+exports.default = fluentIconsAtomicImportLoader;

package/lib/transform.d.ts

@@ -0,0 +1,11 @@
+import MagicString from 'magic-string';
+interface TransformOptions {
+    iconVariant: 'svg' | 'fonts' | 'svg-sprite';
+    path: string;
+}
+export interface TransformResult {
+    code: string;
+    map: ReturnType<MagicString['generateMap']>;
+}
+export declare function transformSource(source: string, options: TransformOptions): TransformResult;
+export {};

package/lib/transform.js

@@ -0,0 +1,75 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformSource = void 0;
+const oxc_parser_1 = require("oxc-parser");
+const magic_string_1 = __importDefault(require("magic-string"));
+const MODULE_NAME = '@fluentui/react-icons';
+const ICON_SUFFIX_REGEX = /(\d*)?(Regular|Filled|Light|Color)$/;
+function getAtomicImportPath(importName, iconVariant) {
+    if (importName === 'useIconContext' || importName === 'IconDirectionContextProvider') {
+        return '@fluentui/react-icons/providers';
+    }
+    const isIcon = importName.match(ICON_SUFFIX_REGEX);
+    if (!isIcon) {
+        return '@fluentui/react-icons/utils';
+    }
+    const withoutSuffix = importName.replace(ICON_SUFFIX_REGEX, '');
+    const kebabCase = withoutSuffix.replace(/[a-z\d](?=[A-Z])|[a-zA-Z](?=\d)|[A-Z](?=[A-Z][a-z])/g, '$&-').toLowerCase();
+    return `@fluentui/react-icons/${iconVariant}/${kebabCase}`;
+}
+function transformSource(source, options) {
+    const { iconVariant, path } = options;
+    const result = (0, oxc_parser_1.parseSync)(path, source, {
+        sourceType: 'module',
+    });
+    if (result.errors.length > 0) {
+        throw new Error(result.errors[0].message);
+    }
+    const { staticImports, staticExports } = result.module;
+    const src = new magic_string_1.default(source);
+    for (const imp of staticImports) {
+        if (imp.moduleRequest.value !== MODULE_NAME)
+            continue;
+        const namedEntries = imp.entries.filter((e) => e.importName.kind === 'Name');
+        if (namedEntries.length === 0)
+            continue;
+        const otherEntries = imp.entries.filter((e) => e.importName.kind !== 'Name');
+        const lines = [];
+        if (otherEntries.length > 0) {
+            const names = otherEntries
+                .map((e) => (e.importName.kind === 'Default' ? e.localName.value : `* as ${e.localName.value}`))
+                .join(', ');
+            lines.push(`import ${names} from '${MODULE_NAME}';`);
+        }
+        for (const entry of namedEntries) {
+            const importedName = entry.importName.name;
+            const localName = entry.localName.value;
+            const newSource = getAtomicImportPath(importedName, iconVariant);
+            const spec = importedName === localName ? importedName : `${importedName} as ${localName}`;
+            lines.push(`import { ${spec} } from '${newSource}';`);
+        }
+        src.overwrite(imp.start, imp.end, lines.join('\n'));
+    }
+    for (const exp of staticExports) {
+        const relevantEntries = exp.entries.filter((e) => e.moduleRequest?.value === MODULE_NAME && e.exportName.kind === 'Name');
+        if (relevantEntries.length === 0)
+            continue;
+        const lines = [];
+        for (const entry of relevantEntries) {
+            const importedName = entry.importName.name;
+            const exportedName = entry.exportName.name;
+            const newSource = getAtomicImportPath(importedName, iconVariant);
+            const spec = importedName === exportedName ? importedName : `${importedName} as ${exportedName}`;
+            lines.push(`export { ${spec} } from '${newSource}';`);
+        }
+        src.overwrite(exp.start, exp.end, lines.join('\n'));
+    }
+    return {
+        code: src.toString(),
+        map: src.generateMap({ hires: true }),
+    };
+}
+exports.transformSource = transformSource;

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@fluentui/react-icons-atomic-webpack-loader",
+  "version": "0.0.1",
+  "description": "Webpack loader that transforms barrel imports and re-exports from @fluentui/react-icons into atomic deep paths",
+  "main": "lib/index.js",
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "webpack -c test/webpack.config.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microsoft/fluentui-system-icons.git",
+    "directory": "packages/react-icons-atomic-webpack-loader"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/microsoft/fluentui-system-icons/issues"
+  },
+  "dependencies": {
+    "magic-string": "^0.30.0",
+    "oxc-parser": "^0.125.0"
+  },
+  "devDependencies": {
+    "@fluentui/react-icons": "*",
+    "ts-loader": "^9.5.0",
+    "typescript": "5.0.4",
+    "webpack": "^5.72.0",
+    "@types/node": "22"
+  },
+  "peerDependencies": {
+    "webpack": ">=5.0.0"
+  },
+  "files": [
+    "lib/*"
+  ]
+}