@fluentui/react-icons-atomic-webpack-loader 0.0.5 → 0.0.6

package/README.md

@@ -72,11 +72,12 @@ module.exports = {
 
 ## Options
 
-| Option            | Type                                   | Default     | Description                                                                |
-| ----------------- | -------------------------------------- | ----------- | -------------------------------------------------------------------------- |
-| `iconVariant`     | `'svg'` \| `'fonts'` \| `'svg-sprite'` | `'svg'`     | Variant icons resolve to. Applied to every supported module.               |
-| `fallbackVariant` | `'svg'` \| `'fonts'` \| `'svg-sprite'` | `undefined` | Variant used for a module that does not support `iconVariant` (see below). |
-| `headless`        | `boolean`                              | `false`     | Resolve to the headless (Griffel-free) build where the module ships one.   |
+| Option                | Type                                   | Default     | Description                                                                             |
+| --------------------- | -------------------------------------- | ----------- | --------------------------------------------------------------------------------------- |
+| `iconVariant`         | `'svg'` \| `'fonts'` \| `'svg-sprite'` | `'svg'`     | Variant icons resolve to. Applied to every supported module.                            |
+| `fallbackVariant`     | `'svg'` \| `'fonts'` \| `'svg-sprite'` | `undefined` | Variant used for a module that does not support `iconVariant` (see below).              |
+| `headless`            | `boolean`                              | `false`     | Resolve to the headless (Griffel-free) build where the module ships one.                |
+| `allowDynamicImports` | `boolean`                              | `false`     | Atomize a narrow, statically-provable subset of dynamic `import()` barrels (see below). |
 
 ### Variant resolution & `fallbackVariant`
 
@@ -247,6 +248,86 @@ flowchart TD
 
 Files that don't reference a supported module are passed through untouched (fast pre-check).
 
+## Limitations
+
+### Dynamic imports are not atomized
+
+The loader only rewrites **static** `import` / `export … from` declarations. A dynamic `import()` of a barrel cannot be atomized, because the returned module-namespace object is a runtime value whose usage the loader cannot statically prove:
+
+```js
+// ⚠️ Not rewritten — the ENTIRE icon set is pulled into the async chunk.
+const { AddFilled } = await import('@fluentui/react-icons');
+React.lazy(() => import('@fluentui/react-icons'));
+```
+
+When it detects a dynamic import of a supported barrel, the loader emits a warning. Import the atomic path directly instead — then you lazy-load only the icons you use:
+
+```js
+// ✅ Only this icon lands in the async chunk.
+const { AddFilled } = await import('@fluentui/react-icons/svg/add');
+```
+
+Alternatively, move the icons behind a local module that statically imports them; the loader atomizes that module, and only your lazy chunk pays for what it uses.
+
+> The same applies to full-barrel subpaths (`@fluentui/react-icons/svg`, `@fluentui/react-icons/fonts`) — dynamically importing those also bundles the whole set. Always target a per-icon atomic path.
+
+### Opt-in: `allowDynamicImports`
+
+> **Prefer a dedicated module of static imports.** The most robust pattern is a
+> small module that statically imports the icons you need and is itself lazy-loaded
+> (`const { AddFilled } = await import('./lazy-icons')`). Static imports are
+> atomized unconditionally, tree-shake predictably, and avoid every gotcha below.
+> Reach for `allowDynamicImports` only when refactoring to that pattern isn't
+> practical.
+
+With `allowDynamicImports: true`, the loader additionally rewrites a **narrow,
+statically-provable** subset of dynamic barrel imports into atomic ones. Only two
+call-site shapes qualify — where the imported names are literals at the `import()`:
+
+```js
+// await + object destructure
+const { AddFilled } = await import('@fluentui/react-icons');
+// → const { AddFilled } = await import('@fluentui/react-icons/svg/add');
+
+// .then + object-pattern callback param
+import('@fluentui/react-icons').then(({ AddFilled }) => …);
+// → import('@fluentui/react-icons/svg/add').then(({ AddFilled }) => …);
+```
+
+Names from the **same** atom are grouped into one import; names from **different**
+atoms become a positional `Promise.all([...])`:
+
+```js
+const { AddFilled, ArrowLeftRegular } = await import('@fluentui/react-icons');
+// →
+const [{ AddFilled }, { ArrowLeftRegular }] = await Promise.all([
+  import('@fluentui/react-icons/svg/add'),
+  import('@fluentui/react-icons/svg/arrow-left'),
+]);
+```
+
+It honors `iconVariant` / `fallbackVariant` / `headless` and per-name color
+rerouting exactly like static imports.
+
+#### Gotchas — what is **not** rewritten (left untouched, still warns)
+
+- **Namespace binding**: `const ns = await import('@fluentui/react-icons')` — `ns`
+  is a runtime object; usage isn't statically known, so the whole set ships.
+- **`.then(m => m.AddFilled)`**: namespace parameter + member access — not a
+  destructure, so the names aren't visible at the call site.
+- **Rest / computed / default / nested patterns**: `{ AddFilled, ...rest }`,
+  `{ [name]: icon }`, `{ AddFilled = fallback }`, `{ Add: { … } }`.
+- **Non-literal specifiers**: `import(pkg)`, template interpolation, or a promise
+  stored in a variable and `.then`-ed elsewhere.
+
+For any of these the loader leaves your code as-is and emits the standard
+"cannot be atomized" warning — the safe default.
+
+> ⚠️ The `Promise.all` rewrite changes the emitted runtime structure (parallel
+> chunk loading, positional destructuring). It's semantically equivalent for the
+> supported shapes, but if you depend on the exact expression shape, prefer the
+> dedicated-module pattern above.
+
 ## Requirements
 
 - `webpack` >= 5

package/lib/index.d.ts

@@ -39,5 +39,23 @@ export interface FluentIconsAtomicImportLoaderOptions {
      * `headless/fonts/styles.css` for font icons) in your app entry point.
      */
     headless?: boolean;
+    /**
+     * Rewrite a **narrow, statically-provable** subset of dynamic `import()` barrel
+     * calls into atomic dynamic imports. Defaults to `false`.
+     *
+     * Only two shapes are rewritten, where the imported names are known literals at
+     * the call site:
+     * - `const { AddFilled } = await import('@fluentui/react-icons')`
+     * - `import('@fluentui/react-icons').then(({ AddFilled }) => …)`
+     *
+     * Names from the same atom are grouped into one import; names from different
+     * atoms become a positional `Promise.all([...])`. Anything else (namespace
+     * binding `const ns = await import(…)`, `.then(m => m.X)`, rest/computed/default
+     * patterns, non-literal specifiers) is left untouched and still warns.
+     *
+     * Prefer a dedicated module of **static** atomic imports that you lazy-load
+     * (`import('./icons')`) over relying on this; see the README for the gotchas.
+     */
+    allowDynamicImports?: boolean;
 }
 export default function fluentIconsAtomicImportLoader(this: LoaderContext<FluentIconsAtomicImportLoaderOptions>, sourceCode: string): void;

package/lib/index.js

@@ -9,7 +9,7 @@ function fluentIconsAtomicImportLoader(sourceCode) {
     if (!modules_1.SUPPORTED_MODULE_NAMES.some((name) => sourceCode.includes(name))) {
         return this.callback(null, sourceCode);
     }
-    const { iconVariant = 'svg', fallbackVariant, headless = false } = this.getOptions();
+    const { iconVariant = 'svg', fallbackVariant, headless = false, allowDynamicImports = false } = this.getOptions();
     let code;
     let map;
     let diagnostics;
@@ -18,6 +18,7 @@ function fluentIconsAtomicImportLoader(sourceCode) {
             iconVariant,
             fallbackVariant,
             headless,
+            allowDynamicImports,
             path: resourcePath,
         }));
     }

package/lib/transform.d.ts

@@ -7,6 +7,12 @@ interface TransformOptions {
     fallbackVariant?: IconVariant;
     /** Resolve to the headless (Griffel-free) build where the module supports it. */
     headless?: boolean;
+    /**
+     * Rewrite a narrow, statically-provable subset of dynamic `import()` barrel
+     * calls into atomic dynamic imports (see {@link rewriteDynamicImports}).
+     * Defaults to `false`. Un-rewritable dynamic barrel imports still warn.
+     */
+    allowDynamicImports?: boolean;
     path: string;
 }
 export interface Diagnostic {

package/lib/transform.js

@@ -8,14 +8,14 @@ const oxc_parser_1 = require("oxc-parser");
 const magic_string_1 = __importDefault(require("magic-string"));
 const modules_1 = require("./modules");
 function transformSource(source, options) {
-    const { iconVariant, fallbackVariant, headless = false, path } = options;
+    const { iconVariant, fallbackVariant, headless = false, allowDynamicImports = false, 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 { staticImports, staticExports, dynamicImports } = result.module;
     const src = new magic_string_1.default(source);
     const diagnostics = [];
     // Dedupe diagnostics by message so a module's variant / color / headless
@@ -134,6 +134,169 @@ function transformSource(source, options) {
             continue;
         src.overwrite(exp.start, exp.end, lines.join('\n'));
     }
+    // Source-literal start offsets of dynamic imports that were atomized below.
+    // Used to suppress the "cannot be atomized" warning for imports we rewrote.
+    const rewrittenImportStarts = new Set();
+    if (allowDynamicImports) {
+        /**
+         * Resolves one destructured binding name to the atomic subpath it should be
+         * imported from, honoring the active `iconVariant` / `headless` / color rules
+         * (same policy as static imports). Returns `null` when the owning module can't
+         * be resolved — `targetFor` has already recorded an error diagnostic — which
+         * signals the caller to bail and leave the dynamic import untouched.
+         *
+         * @example
+         * // iconVariant: 'svg'
+         * resolveNameSource(reactIcons, 'AddFilled')   // → '@fluentui/react-icons/svg/add'
+         * resolveNameSource(reactIcons, 'bundleIcon')  // → '@fluentui/react-icons/utils'
+         * // iconVariant: 'fonts'
+         * resolveNameSource(reactIcons, 'AddFilled')   // → '@fluentui/react-icons/fonts/add'
+         */
+        const resolveNameSource = (descriptor, importedName) => {
+            const target = targetFor(descriptor, (0, modules_1.isColorIconName)(importedName));
+            if (!target)
+                return null;
+            return descriptor.resolve(importedName, target.variant, target.headless);
+        };
+        /**
+         * Groups the properties of a destructuring object pattern by the atomic module
+         * each imported name resolves to, preserving first-seen order. Each group's
+         * `specs` are the emit-ready specifier strings (`'AddFilled'`, or
+         * `'ArrowLeftRegular: arrow'` for a rename).
+         *
+         * Returns `null` (bail — leave the dynamic import untouched) when any property
+         * isn't a plain, statically-known `name → binding` pair: rest elements,
+         * computed/string keys, default values, or nested patterns.
+         *
+         * @example
+         * // `{ AddFilled, AddRegular }`  — both live in the `add` atom
+         * // → [{ source: '@fluentui/react-icons/svg/add', specs: ['AddFilled', 'AddRegular'] }]
+         *
+         * @example
+         * // `{ AddFilled, ArrowLeftRegular: arrow }`  — different atoms, one renamed
+         * // → [
+         * //     { source: '@fluentui/react-icons/svg/add',        specs: ['AddFilled'] },
+         * //     { source: '@fluentui/react-icons/svg/arrow-left', specs: ['ArrowLeftRegular: arrow'] },
+         * //   ]
+         *
+         * @example
+         * // `{ AddFilled, ...rest }`  → null   (rest element → bail)
+         */
+        const buildGroups = (objectPattern, descriptor) => {
+            const bySource = new Map();
+            const order = [];
+            for (const prop of objectPattern.properties) {
+                if (prop.type !== 'Property' || prop.computed || prop.kind !== 'init')
+                    return null;
+                if (prop.key.type !== 'Identifier' || prop.value.type !== 'Identifier')
+                    return null;
+                const importedName = prop.key.name;
+                const localName = prop.value.name;
+                const resolvedSource = resolveNameSource(descriptor, importedName);
+                if (resolvedSource === null)
+                    return null;
+                const spec = importedName === localName ? importedName : `${importedName}: ${localName}`;
+                if (!bySource.has(resolvedSource)) {
+                    bySource.set(resolvedSource, []);
+                    order.push(resolvedSource);
+                }
+                bySource.get(resolvedSource).push(spec);
+            }
+            if (order.length === 0)
+                return null;
+            return order.map((groupSource) => ({ source: groupSource, specs: bySource.get(groupSource) }));
+        };
+        const importCallText = (groups) => groups.length === 1
+            ? `import('${groups[0].source}')`
+            : `Promise.all([${groups.map((g) => `import('${g.source}')`).join(', ')}])`;
+        const patternText = (groups) => groups.length === 1
+            ? `{ ${groups[0].specs.join(', ')} }`
+            : `[${groups.map((g) => `{ ${g.specs.join(', ')} }`).join(', ')}]`;
+        const visitor = new oxc_parser_1.Visitor({
+            // `const { A, B } = await import('barrel')`
+            VariableDeclarator(node) {
+                if (node.id.type !== 'ObjectPattern' ||
+                    node.init?.type !== 'AwaitExpression' ||
+                    node.init.argument.type !== 'ImportExpression') {
+                    return;
+                }
+                const importExpr = node.init.argument;
+                if (importExpr.source.type !== 'Literal' || typeof importExpr.source.value !== 'string')
+                    return;
+                const descriptor = (0, modules_1.getModuleDescriptor)(importExpr.source.value);
+                if (!descriptor)
+                    return;
+                const groups = buildGroups(node.id, descriptor);
+                if (!groups)
+                    return;
+                src.overwrite(node.start, node.end, `${patternText(groups)} = await ${importCallText(groups)}`);
+                rewrittenImportStarts.add(importExpr.source.start);
+            },
+            // `import('barrel').then(({ A, B }) => …)`
+            CallExpression(node) {
+                if (node.callee.type !== 'MemberExpression' ||
+                    node.callee.computed ||
+                    node.callee.property.type !== 'Identifier' ||
+                    node.callee.property.name !== 'then' ||
+                    node.callee.object.type !== 'ImportExpression') {
+                    return;
+                }
+                const importExpr = node.callee.object;
+                if (importExpr.source.type !== 'Literal' || typeof importExpr.source.value !== 'string')
+                    return;
+                const descriptor = (0, modules_1.getModuleDescriptor)(importExpr.source.value);
+                if (!descriptor)
+                    return;
+                const callback = node.arguments[0];
+                if (!callback || (callback.type !== 'ArrowFunctionExpression' && callback.type !== 'FunctionExpression')) {
+                    return;
+                }
+                const param = callback.params[0];
+                if (param?.type !== 'ObjectPattern')
+                    return;
+                const groups = buildGroups(param, descriptor);
+                if (!groups)
+                    return;
+                src.overwrite(importExpr.start, importExpr.end, importCallText(groups));
+                // Multiple atoms resolve to an array, so the callback must destructure by
+                // position instead of by name.
+                if (groups.length > 1) {
+                    src.overwrite(param.start, param.end, patternText(groups));
+                }
+                rewrittenImportStarts.add(importExpr.source.start);
+            },
+        });
+        visitor.visit(result.program);
+    }
+    // Dynamic imports of a barrel (`import('@fluentui/react-icons')`) cannot be
+    // atomized: the returned namespace object is a runtime value whose usage is
+    // not statically known, so the whole icon set ends up in the async chunk. We
+    // can't rewrite it safely, but we can warn and point at the atomic escape
+    // hatch (`import('@fluentui/react-icons/svg/add')`). Atomic and subpath
+    // requests don't match a barrel descriptor, so they never warn.
+    for (const dyn of dynamicImports) {
+        const request = dyn.moduleRequest;
+        if (!request)
+            continue;
+        // Skip imports we already atomized above (their usage was statically provable).
+        if (rewrittenImportStarts.has(request.start))
+            continue;
+        // Unlike static imports, oxc doesn't resolve a dynamic import's argument to a
+        // specifier value — it's an arbitrary expression. Match the raw span against
+        // each supported module's quoted spellings; this naturally ignores variables,
+        // interpolated templates, and subpath/atomic requests (module names never
+        // contain quotes).
+        const raw = source.slice(request.start, request.end);
+        const moduleName = modules_1.SUPPORTED_MODULE_NAMES.find((name) => raw === `'${name}'` || raw === `"${name}"` || raw === `\`${name}\``);
+        if (!moduleName)
+            continue;
+        pushDiagnostic({
+            level: 'warning',
+            message: `dynamic import of the "${moduleName}" barrel cannot be atomized, so the entire icon ` +
+                `set will be bundled into the async chunk. Import an atomic path directly instead, ` +
+                `e.g. import('${moduleName}/svg/add').`,
+        });
+    }
     return {
         code: src.toString(),
         map: src.generateMap({ hires: true }),

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@fluentui/react-icons-atomic-webpack-loader",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "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": "vitest run && webpack -c test/webpack.config.js"
+    "build": "yarn run -T tsc -p .",
+    "lint": "yarn run -T eslint package.json",
+    "test": "yarn run -T vitest run && yarn run -T webpack -c test/webpack.config.js"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -24,11 +25,7 @@
     "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"
+    "@fluentui/react-icons": "*"
   },
   "peerDependencies": {
     "webpack": ">=5.0.0"