@uxf/icons-generator 11.129.0 → 12.1.0

package/README.md

@@ -17,7 +17,7 @@ This is a build-time dev tool run via the `icons-gen` binary. The runtime `<Icon
 yarn add -D @uxf/icons-generator
 ```
 
-Requires Node `>= 24`. Peer dependency: `@uxf/core` (`11.114.0`). To use the Font Awesome Pro adapter, additionally install the per-style FA packages you reference (see [Providers](#providers--font-awesome-pro-adapter)).
+Requires Node `>= 24`. Peer dependency: `@uxf/core` (`11.114.0`). The Font Awesome Pro adapter needs no extra packages — it streams icons from the kit at generation time, so it only needs the `@awesome.me` scope to resolve through your registry (see [Providers](#providers--font-awesome-pro-adapter)).
 
 ## Quick start
 
@@ -145,40 +145,45 @@ This augmentation is what makes `@uxf/ui/icon`'s `IconName` (`keyof IconsSet`) a
 
 ## Providers — Font Awesome Pro adapter
 
-The `faPro` adapter reads icon data from the per-style Font Awesome packages. Install only the styles you actually use.
-
-| Namespace                 | Package                                        |
-| ------------------------- | ---------------------------------------------- |
-| `brands.*`                | `@fortawesome/free-brands-svg-icons`           |
-| `regular.*`               | `@fortawesome/pro-regular-svg-icons`           |
-| `solid.*`                 | `@fortawesome/pro-solid-svg-icons`             |
-| `light.*`                 | `@fortawesome/pro-light-svg-icons`             |
-| `thin.*`                  | `@fortawesome/pro-thin-svg-icons`              |
-| `duotone.*`               | `@fortawesome/pro-duotone-svg-icons`           |
-| `duotone-regular.*`       | `@fortawesome/duotone-regular-svg-icons`       |
-| `duotone-light.*`         | `@fortawesome/duotone-light-svg-icons`         |
-| `duotone-thin.*`          | `@fortawesome/duotone-thin-svg-icons`          |
-| `sharp-regular.*`         | `@fortawesome/sharp-regular-svg-icons`         |
-| `sharp-solid.*`           | `@fortawesome/sharp-solid-svg-icons`           |
-| `sharp-light.*`           | `@fortawesome/sharp-light-svg-icons`           |
-| `sharp-thin.*`            | `@fortawesome/sharp-thin-svg-icons`            |
-| `sharp-duotone-regular.*` | `@fortawesome/sharp-duotone-regular-svg-icons` |
-| `sharp-duotone-solid.*`   | `@fortawesome/sharp-duotone-solid-svg-icons`   |
-| `sharp-duotone-light.*`   | `@fortawesome/sharp-duotone-light-svg-icons`   |
-| `sharp-duotone-thin.*`    | `@fortawesome/sharp-duotone-thin-svg-icons`    |
-
-An icon is referenced as `"<namespace>.<kebab-icon-name>"` (e.g. `"regular.calendar-check"`). The legacy `@fortawesome/fontawesome-pro` monolith is no longer supported — the adapter throws if it is installed, so uninstall it.
-
-### Local development setup
+The `faPro` adapter resolves icons from a Font Awesome **kit** package (`@awesome.me/kit-…`), the
+only distribution channel that carries every style FA 7 offers. Nothing is installed: at generation
+time the CLI streams the kit tarball, pulls out just the SVGs your config names, and discards the
+rest. A ~110 MB archive therefore leaves behind a few kilobytes and never lands in `node_modules`
+or a Docker image.
 
-```bash
-# Set registry and token
-npm config set "@fortawesome:registry" https://npm.fontawesome.com/
-npm config set "//npm.fontawesome.com/:_authToken" YOUR_TOKEN
+### Resolution order
 
-# Install only the styles you use
-npm install --save-dev @fortawesome/pro-regular-svg-icons @fortawesome/free-brands-svg-icons
-```
+For each `"<namespace>.<icon-name>"` the adapter tries, in order:
+
+1. **An installed `@fortawesome/*-svg-icons` package** — deprecated, kept so existing projects keep
+   building. Using one prints a warning; support is removed in a future major.
+2. **The streamed kit package** — the supported path.
+3. **`<configDirectory>/icons-fallbacks/faPro.json`** — the snapshot written on every successful
+   resolve, so a project without Font Awesome access can still rebuild the icons it already has.
+
+The monolithic `@fortawesome/fontawesome-pro` is no longer supported at all: the adapter throws if
+it finds it installed.
+
+### Registry access
+
+Kits live in the `@awesome.me` scope on Font Awesome's own registry, so that scope has to resolve
+through our Verdaccio (which caches the tarballs, keeping FA bandwidth costs down). See
+`docs/recipes/fontawesome-kit-verdaccio.md` for the server side, and
+`docs/migration/fa-pro-kit-stream.md` for what a consuming project has to change.
+
+Registry and credentials are read from the same `.npmrc` and `.yarnrc.yml` files your package
+manager uses — npm-based and Yarn-based projects both work without extra configuration.
+
+### Namespaces
+
+A namespace is the style directory inside the package, so `"regular.calendar-check"` resolves to
+`regular/calendar-check.svg`. For the classic families it matches what the per-style packages used:
+`brands`, `regular`, `solid`, `light`, `thin`, `duotone`, `duotone-regular`, `duotone-light`,
+`duotone-thin`, and the `sharp-` and `sharp-duotone-` variants of each. Styles a kit adds on top
+appear under their own directory name.
+
+The exhaustive list is the generated `FaProIconName` union in `src/fa-pro-types.ts`, regenerated by
+`npm run icon-types:gen` in this monorepo.
 
 ### Usage
 
@@ -196,11 +201,43 @@ module.exports = {
 };
 ```
 
-`faPro.adapter([...])` names each icon `faPro_<namespace>.<name>`, while `faPro.icon(...)` lets you assign a custom key.
+`faPro.adapter([...])` names each icon `faPro_<namespace>.<name>`, while `faPro.icon(...)` lets you
+assign a custom key. Both register the icon for the prefetch that runs before generation, so they
+must be called while the config module is being loaded — which is what the examples above do.
+
+### Which kit version, and how it is upgraded
+
+The kit **and its version** are pinned in `src/utils/_faProTarballCache.ts`, next to the generated
+`FaProIconName` union they belong to. Both ship in this package, so a project gets a matched pair and
+never has to configure a version: bumping `@uxf/icons-generator` is how you move to a newer kit.
+
+That also means a warm run needs no registry access at all, and that a kit republished upstream
+cannot change anybody's sprite behind their back.
+
+Adopting a new kit version is one commit here:
+
+```bash
+UXF_FA_PRO_VERSION=latest npx tsx packages/icons-generator/scripts/generate-fa-pro-types.ts  # what is out there?
+# set DEFAULT_VERSION in src/utils/_faProTarballCache.ts to that version
+npm run icon-types:gen
+```
+
+The generator refuses to write a union built from a version other than the pinned one, so the two
+cannot drift.
+
+### Caching
 
-### Without the private key
+Fetched SVGs and the package's icon-name index are cached under
+`~/.cache/uxf-icons-generator/fa-pro/v<schema>/<package>_<version>/` — the package and version are
+slugified, so the real directory looks like `v2/_awesome.me_kit-0618a3d496_1.0.2`. A run that introduces no new icon
+performs no network I/O. Point `UXF_FA_PRO_CACHE_ROOT` somewhere inside the build directory to let
+CI cache it; a version bump simply misses the cache and refills it.
 
-If your project already has generated icons, the Font Awesome Pro packages are not required to rebuild them. On each successful resolve the adapter caches the icon into `<configDirectory>/icons-fallbacks/faPro.json`; when a package is missing, it reads from that fallback file instead. Existing icons keep working, but **adding new** provider icons still requires the corresponding FA package installed.
+| Variable                | Default                        | Purpose                                                                       |
+| ----------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
+| `UXF_FA_PRO_PACKAGE`    | `@awesome.me/kit-0618a3d496`   | Source package. Accepts any kit, or `@fortawesome/fontawesome-pro`.           |
+| `UXF_FA_PRO_VERSION`    | the pinned `DEFAULT_VERSION`   | Override the version. `latest` asks the registry — for discovery, not builds. |
+| `UXF_FA_PRO_CACHE_ROOT` | `~/.cache/uxf-icons-generator` | Where cached SVGs and the index live.                                         |
 
 ## Generated output
 
@@ -273,6 +310,10 @@ declare module "@uxf/ui/icon/theme" {
 - **Paths are `cwd`-relative and need slashes.** `configDirectory` and `generatedDirectory` are joined onto `process.cwd()`, so both must start and end with `/`.
 - **`typescript: false` currently has no effect.** The generator always emits `icons.ts` — the flag falls back to `true` internally.
 - **The `faPro` provider is a deep import:** `@uxf/icons-generator/src/providers/fa-pro` (the published files preserve the `src/` layout). The `IconsConfig` type is at `@uxf/icons-generator/src/types`.
+- **Provider icons are resolved before generation, not lazily.** `faPro.icon(...)` and
+  `faPro.adapter([...])` register their names when the config module loads, and the CLI resolves
+  them all in one streamed pass. Building an icon name inside a callback that runs later than config
+  load will not be prefetched.
 - **Keep the default `moduleName`** (`@uxf/ui/icon/theme`) unless you intentionally augment a different module; changing it breaks the `@uxf/ui` `IconName` inference.
 
 ## Links

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uxf/icons-generator",
-    "version": "11.129.0",
+    "version": "12.1.0",
     "description": "",
     "main": "index.js",
     "scripts": {
@@ -25,23 +25,6 @@
         "@uxf/core": "11.129.0"
     },
     "devDependencies": {
-        "@fortawesome/duotone-light-svg-icons": "7.3.1",
-        "@fortawesome/duotone-regular-svg-icons": "7.3.1",
-        "@fortawesome/duotone-thin-svg-icons": "7.3.1",
-        "@fortawesome/free-brands-svg-icons": "7.3.1",
-        "@fortawesome/pro-duotone-svg-icons": "7.3.1",
-        "@fortawesome/pro-light-svg-icons": "7.3.1",
-        "@fortawesome/pro-regular-svg-icons": "7.3.1",
-        "@fortawesome/pro-solid-svg-icons": "7.3.1",
-        "@fortawesome/pro-thin-svg-icons": "7.3.1",
-        "@fortawesome/sharp-duotone-light-svg-icons": "7.3.1",
-        "@fortawesome/sharp-duotone-regular-svg-icons": "7.3.1",
-        "@fortawesome/sharp-duotone-solid-svg-icons": "7.3.1",
-        "@fortawesome/sharp-duotone-thin-svg-icons": "7.3.1",
-        "@fortawesome/sharp-light-svg-icons": "7.3.1",
-        "@fortawesome/sharp-regular-svg-icons": "7.3.1",
-        "@fortawesome/sharp-solid-svg-icons": "7.3.1",
-        "@fortawesome/sharp-thin-svg-icons": "7.3.1",
         "@types/node": "24",
         "@uxf/core": "11.129.0",
         "tsx": "4.23.12"

package/scripts/generate-fa-pro-types.d.ts

@@ -0,0 +1 @@
+export {};

package/scripts/generate-fa-pro-types.js

@@ -1,93 +1,54 @@
 "use strict";
-
-const { existsSync, writeFileSync } = require("fs");
-const path = require("path");
-
-// Keep in sync with NAMESPACE_TO_PACKAGE in src/providers/fa-pro.ts.
-const NAMESPACE_TO_PACKAGE = {
-    brands: "@fortawesome/free-brands-svg-icons",
-    duotone: "@fortawesome/pro-duotone-svg-icons",
-    "duotone-light": "@fortawesome/duotone-light-svg-icons",
-    "duotone-regular": "@fortawesome/duotone-regular-svg-icons",
-    "duotone-thin": "@fortawesome/duotone-thin-svg-icons",
-    light: "@fortawesome/pro-light-svg-icons",
-    regular: "@fortawesome/pro-regular-svg-icons",
-    "sharp-duotone-light": "@fortawesome/sharp-duotone-light-svg-icons",
-    "sharp-duotone-regular": "@fortawesome/sharp-duotone-regular-svg-icons",
-    "sharp-duotone-solid": "@fortawesome/sharp-duotone-solid-svg-icons",
-    "sharp-duotone-thin": "@fortawesome/sharp-duotone-thin-svg-icons",
-    "sharp-light": "@fortawesome/sharp-light-svg-icons",
-    "sharp-regular": "@fortawesome/sharp-regular-svg-icons",
-    "sharp-solid": "@fortawesome/sharp-solid-svg-icons",
-    "sharp-thin": "@fortawesome/sharp-thin-svg-icons",
-    solid: "@fortawesome/pro-solid-svg-icons",
-    thin: "@fortawesome/pro-thin-svg-icons",
-};
-
-const LEGACY_PACKAGE = "@fortawesome/fontawesome-pro";
-
-const NODE_MODULES_PATH = process.env.NODE_MODULES_PATH ?? path.join(__dirname, "../../../node_modules");
-
-const collectIconNames = (pkgName) => {
-    const pkgPath = path.join(NODE_MODULES_PATH, pkgName);
-    if (!existsSync(pkgPath)) {
-        return null;
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable no-console */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const _faProTarballCache_1 = require("../src/utils/_faProTarballCache");
+const OUTPUT_FILE = (0, path_1.join)(__dirname, "../src/fa-pro-types.ts");
+/**
+ * Regenerate the `FaProIconName` union from the icons the configured Font
+ * Awesome package actually ships.
+ *
+ * The package is the single source of truth on purpose: the file is committed
+ * and CI verifies it with `git diff --exit-code`, so a second source (installed
+ * `@fortawesome/*-svg-icons` packages, which omit every alias) would make the
+ * output depend on what happens to be in `node_modules`.
+ */
+async function generate() {
+    var _a, _b, _c;
+    const source = await (0, _faProTarballCache_1._resolveFaProSource)();
+    // The union and the pinned version travel in the same tarball, so they must
+    // describe the same archive. Generating from anything else would ship a type
+    // that promises icons the runtime will not find (or hide ones it would).
+    const expected = (0, _faProTarballCache_1._getFaProDefaultVersion)();
+    if (source.version !== expected) {
+        throw new Error(`Refusing to generate types from ${source.package}@${source.version} while the package is pinned to ${expected}.\n` +
+            `To adopt a new kit: set DEFAULT_VERSION in src/utils/_faProTarballCache.ts to "${source.version}", then run this again.`);
     }
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const pkgExports = require(pkgPath);
-    const names = new Set();
-    for (const value of Object.values(pkgExports)) {
-        if (value && typeof value === "object" && typeof value.iconName === "string") {
-            names.add(value.iconName);
-        }
-    }
-    return [...names].sort();
-};
-
-const generate = () => {
-    if (existsSync(path.join(NODE_MODULES_PATH, LEGACY_PACKAGE))) {
-        throw new Error(
-            `Package "${LEGACY_PACKAGE}" is installed but no longer used. The faPro adapter reads from per-style packages instead. Run \`yarn remove ${LEGACY_PACKAGE}\`.`,
-        );
+    const index = await (0, _faProTarballCache_1._getFaProIndex)();
+    const namespaces = Object.keys(index.icons).sort();
+    if (namespaces.length === 0) {
+        throw new Error(`${source.package}@${source.version} contains no icon SVGs. Check the package contents.`);
     }
-
     const names = [];
-    const found = [];
-    const missing = [];
-
-    for (const [namespace, pkgName] of Object.entries(NAMESPACE_TO_PACKAGE)) {
-        const iconNames = collectIconNames(pkgName);
-        if (iconNames === null) {
-            missing.push(`${namespace} (${pkgName})`);
-            continue;
-        }
-        found.push(`${namespace}: ${iconNames.length}`);
-        for (const iconName of iconNames) {
+    for (const namespace of namespaces) {
+        for (const iconName of (_a = index.icons[namespace]) !== null && _a !== void 0 ? _a : []) {
             names.push(`"${namespace}.${iconName}"`);
         }
     }
-
-    if (names.length === 0) {
-        throw new Error(
-            "No Font Awesome per-style packages found. Install at least one, e.g. `yarn add -D @fortawesome/pro-regular-svg-icons`.",
-        );
+    (0, fs_1.writeFileSync)(OUTPUT_FILE, `export type FaProIconName = ${names.join(" | ")};\n`);
+    console.log(`Generated ${names.length} icon names from ${source.package}@${source.version}.`);
+    for (const namespace of namespaces) {
+        console.log(`  ${namespace}: ${(_c = (_b = index.icons[namespace]) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0}`);
     }
-
-    writeFileSync(
-        path.join(__dirname, "../src/fa-pro-types.ts"),
-        `export type FaProIconName = ${names.join(" | ")};\n`,
-    );
-
-    console.log(`Generated ${names.length} FA Pro icon names from ${found.length} package(s).`);
-    for (const line of found) {
-        console.log(`  ${line}`);
-    }
-    if (missing.length > 0) {
-        console.log(`Skipped (not installed):`);
-        for (const line of missing) {
-            console.log(`  ${line}`);
-        }
+}
+generate().catch((error) => {
+    console.error(`Failed to generate FA Pro icon types from ${(0, _faProTarballCache_1._getFaProPackage)()}.`);
+    // Only guess at the cause when the error is not already explaining itself,
+    // otherwise the advice contradicts the message right below it.
+    if (error instanceof Error && /\d{3} for |fetch|ENOTFOUND|dist-tag/.test(error.message)) {
+        console.error(`The registry could not be reached — check that the package's scope is proxied, see docs/recipes/fontawesome-kit-verdaccio.md.`);
     }
-};
-
-generate();
+    console.error(error);
+    process.exitCode = 1;
+});