react-native-nano-icons 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Software Mansion <swmansion.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# react-native-nano-icons
+
+**High-performance, build-time icon font generation for React Native & Expo.**
+
+`react-native-nano-icons` automates the conversion of SVG directories into optimized, **multi-color-aware** native fonts and strictly typed TypeScript component factories. It leverages a WebAssembly-powered skia pathops binary build pipeline to ensure pixel-perfect geometry and zero runtime overhead.
+
+---
+
+## 🧩 Platforms Supported
+
+- [x] iOS
+- [x] Android
+- [x] Web
+
+> [!NOTE]
+> `<filter>` and `<mask>` are not yet supported, due to native fonts' glyph limitations.
+> In order to leverage those features, use [`react-native-svg`](https://github.com/software-mansion/react-native-svg) or [`expo-image`](https://docs.expo.dev/versions/latest/sdk/image/)
+
+## 🚀 Usage
+
+### 1. Installation
+
+```bash
+npm install react-native-nano-icons
+```
+
+### 2. Configuration
+
+#### 2.1. Expo
+
+The library uses an Expo Config Plugin to hook into the prebuild phase. This automatically generates the `.ttf` and corresponding `glyphmap` files and links them to the native iOS/Android project's assets.
+
+`app.json`
+
+```JSON
+{
+  "expo": {
+    "plugins": [
+      [
+        "react-native-nano-icons",
+        {
+          "iconSets": [
+            {
+              "inputDir": "./assets/icons/user"
+            }
+          ]
+        }
+      ]
+    ]
+  }
+}
+```
+
+<details>
+<summary>All iconSets Entry Plugin Options</summary>
+
+The plugin accepts an object with an `iconSets` array, allowing you to generate multiple distinct fonts in a single build.
+
+| Property       | Type     | Required | Default        | Description                                                                                                                |
+| :------------- | :------- | :------- | :------------- | :------------------------------------------------------------------------------------------------------------------------- |
+| `inputDir`     | `string` | **Yes**  | —              | Path to the directory containing your `.svg` files (e.g., `./assets/icons/ui`).                                            |
+| `fontFamily`   | `string` | No       | Folder Name    | The name of the generated font family and file. If omitted, the name of the `inputDir` folder is used (e.g., `ui`).        |
+| `outputDir`    | `string` | No       | `../nanoicons` | Path where the `.ttf` and `.json` artifacts will be saved. Defaults to a sibling `nanoicons` folder relative to the input. |
+| `upm`          | `number` | No       | `1024`         | Units Per Em. Defines the resolution of the font grid.                                                                     |
+| `startUnicode` | `string` | No       | `0xe900`       | The starting Hex Unicode point for the first icon glyph.                                                                   |
+
+  <details>
+  <summary>Default Dir Path Behavior</summary>
+  If you do not specify an `outputDir` or `fontFamily`, the library attempts to keep your project organized by creating a   sibling folder.
+
+- **Input:** `./assets/icons/user`
+- **Resulting Output:** `./assets/icons/nanoicons/user.ttf` & `user.glyphmap.json`
+  </details>
+  </details>
+
+#### 2.2 Bare React Native/React Native Web (no Expo)
+
+Bare apps don’t have a prebuild step, so you run the same pipeline via the CLI and ship the built fonts into the native project yourself:
+
+1. **Config** – At the app root, add a `.nanoicons.json` with the same `iconSets` shape as the Expo plugin (see "All iconSets Entry Plugin Options above").
+   <details>
+    <summary>.nanoicons.json example</summary>
+    
+    ```JSON
+    {
+      "iconSets": [
+        {
+          "inputDir": "./assets/icons/user"
+        }
+      ]
+    }
+    ```
+    
+    </details>
+
+2. **Build and link** – From the app root run:
+
+   ```sh
+   npx react-native-nano-icons
+   ```
+
+   This works exactly like the config plugin, removing any necessity for manual Xcode/Android Studio steps.
+
+### 3. Creating an Icon Set Component
+
+Use the factory function to create a fully typed component for your specific icon set. This enables multiple distinct sets (e.g., "Outlined", "Solid", "Brand") within a single app.
+
+`src/components/UserIcon.tsx`
+
+```TypeScript
+import { createNanoIconSet } from "react-native-nano-icons";
+// auto-generated during build-time in outputDir
+import glyphMap from "../../assets/nanoicons/UserIcons.glyphmap.json";
+
+export const UserIcon = createNanoIconSet(glyphMap);
+```
+
+### 4. Component Usage
+
+The generated component supports standard `Text` props **excluding** `style.color | .fontWeight | .fontFamily`.
+
+To manipulate the color(s) of the icon you should provide `colorPalette: ColorValue[]`.
+
+The `name` prop corresponds to **the original name of the svg file** for a given icon.
+
+```TypeScript
+import { Text } from 'react-native'
+import { UserIcon } from './components/UserIcon';
+
+export default function App() {
+  return (
+    <>
+      // Renders the icon with its original multi-color layers from the SVG
+      <UserIcon name="avatar-1" size={32} />
+
+      // Overrides all color layers with the provided colors respectively
+      <UserIcon name="avatar-1" size={24} colorPalette={["blue", "#ffffff", "#fc2930"]} />
+
+      // Renders icon inline within a paragraph
+      <Text>
+        User <UserIcon name="avatar-1" size={12}  /> liked your photo!
+      </Text>
+    </>
+  );
+}
+```
+
+Your color icons can have as many colors as your original svg has, therefore you should experiment to establish which element of the array corresponds to the layer you aim to change the color of.
+If the icon is single-color by design (which results in creating a single glyph during build-time) only the first element is took into consideration, and if the `colorPalette` array is too short - the last color is repeated.
+
+### 5. Font Regeneration
+
+The script detects changes in path and contents of the SVGs in your input directory based on a fingerprint hash. If anything changed, or the output font files are deleted, a given icon-set is regenerated.
+
+> [!IMPORTANT]
+> **You should always verify your icons visually.**
+
+---
+
+## 💡 Architecture & Pipeline & Examples
+
+see [MOTIVATION.md](docs/MOTIVATION.md)
+
+---
+
+## License
+
+`react-native-nano-icons` is released under the **MIT License**. See [LICENSE](LICENSE) for the full text.
+
+---
+
+Built by [Software Mansion](https://swmansion.com/).
+
+[<img width="128" height="69" alt="Software Mansion Logo" src="https://github.com/user-attachments/assets/f0e18471-a7aa-4e80-86ac-87686a86fe56" />](https://swmansion.com/)

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require('./lib/commonjs/plugin/src/index').default;

package/lib/commonjs/cli/build.d.ts

@@ -0,0 +1,28 @@
+import type { NanoLogger } from './logger.js';
+export type IconSetConfig = {
+    /** Path to folder of SVG files (relative to project root). */
+    inputDir: string;
+    /** Font family name (used for TTF and glyphmap filenames). */
+    fontFamily?: string;
+    /** Path where .ttf and .glyphmap.json will be saved. Defaults to a sibling nanoicons folder relative to inputDir. */
+    outputDir?: string;
+    /** Units per em (default 1024). */
+    upm?: number;
+    /** Safe zone inside UPM for glyphs (default 1020). */
+    safeZone?: number;
+    /** First Unicode codepoint for glyphs (default 0xe900). Hex string or number. */
+    startUnicode?: number | string;
+};
+export type BuiltFont = {
+    fontFamily: string;
+    ttfPath: string;
+    glyphmapPath: string;
+};
+/**
+ * Build TTF + glyphmap for all icon sets using a single Pyodide/PathKit instance.
+ * Output is placed in a "nanoicons" folder next to each input dir (sibling to inputDir).
+ * Skips generation for a set if that output folder already contains the expected .ttf and .glyphmap.json.
+ */
+export declare function buildAllFonts(iconSets: IconSetConfig[], projectRoot: string, options?: {
+    logger?: NanoLogger;
+}): Promise<BuiltFont[]>;

package/lib/commonjs/cli/build.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAllFonts = buildAllFonts;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const index_js_1 = require("../src/core/pipeline/index.js");
+const fingerPrint_js_1 = require("../src/utils/fingerPrint.js");
+const DEFAULT_SAFE_ZONE = 1020;
+const DEFAULT_UPM = 1024;
+const DEFAULT_START_UNICODE = 0xe900;
+function shouldSkipGeneration(inputHash, outputDir, fontFamily, logger) {
+    const ttfPath = path_1.default.join(outputDir, `${fontFamily}.ttf`);
+    const glyphmapPath = path_1.default.join(outputDir, `${fontFamily}.glyphmap.json`);
+    if (!fs_1.default.existsSync(outputDir) ||
+        !fs_1.default.existsSync(ttfPath) ||
+        !fs_1.default.existsSync(glyphmapPath)) {
+        return false;
+    }
+    const glyphmap = JSON.parse(fs_1.default.readFileSync(glyphmapPath, 'utf8'));
+    const storedHash = glyphmap?.meta?.hash;
+    if (storedHash && storedHash === inputHash) {
+        logger?.info(`${fontFamily}: SVG fingerprint unchanged, skipping build.`);
+        return true;
+    }
+    return false;
+}
+/**
+ * Build TTF + glyphmap for all icon sets using a single Pyodide/PathKit instance.
+ * Output is placed in a "nanoicons" folder next to each input dir (sibling to inputDir).
+ * Skips generation for a set if that output folder already contains the expected .ttf and .glyphmap.json.
+ */
+async function buildAllFonts(iconSets, projectRoot, options) {
+    const logger = options?.logger;
+    const results = [];
+    let allSkipped = true;
+    for (let i = 0; i < iconSets.length; i++) {
+        const set = iconSets[i];
+        const inputDir = path_1.default.resolve(projectRoot, set.inputDir);
+        const fontFamily = set.fontFamily ?? path_1.default.basename(inputDir);
+        if (!fs_1.default.existsSync(inputDir)) {
+            throw new Error(`[react-native-nano-icons] Input directory does not exist: ${inputDir} (from "${set.inputDir}")`);
+        }
+        const outputDir = set.outputDir
+            ? path_1.default.resolve(projectRoot, set.outputDir)
+            : path_1.default.join(path_1.default.dirname(inputDir), 'nanoicons');
+        const ttfPath = path_1.default.join(outputDir, `${fontFamily}.ttf`);
+        const glyphmapPath = path_1.default.join(outputDir, `${fontFamily}.glyphmap.json`);
+        const inputHash = (0, fingerPrint_js_1.getFingerprintSync)(inputDir);
+        if (shouldSkipGeneration(inputHash, outputDir, fontFamily, logger)) {
+            results.push({ fontFamily, ttfPath, glyphmapPath });
+            continue;
+        }
+        if (fs_1.default.existsSync(ttfPath))
+            fs_1.default.unlinkSync(ttfPath);
+        if (fs_1.default.existsSync(glyphmapPath))
+            fs_1.default.unlinkSync(glyphmapPath);
+        allSkipped = false;
+        const tempDir = path_1.default.join(projectRoot, '.temp_layers', fontFamily);
+        const config = {
+            fontFamily,
+            upm: set.upm ?? DEFAULT_UPM,
+            safeZone: set.safeZone ?? DEFAULT_SAFE_ZONE,
+            startUnicode: set.startUnicode !== undefined
+                ? typeof set.startUnicode === 'string'
+                    ? parseInt(set.startUnicode, 16)
+                    : set.startUnicode
+                : DEFAULT_START_UNICODE,
+        };
+        logger?.start(`Building ${fontFamily} (${i + 1}/${iconSets.length})…`);
+        const out = await (0, index_js_1.runPipeline)(config, { inputDir, outputDir, tempDir }, { logger, inputHash });
+        results.push({
+            fontFamily,
+            ttfPath: out.ttfPath,
+            glyphmapPath: out.glyphmapPath,
+        });
+    }
+    if (allSkipped && results.length > 0) {
+        logger?.succeed('Your icons are flight-tuned with react-native-nano-icons');
+    }
+    return results;
+}

package/lib/commonjs/cli/config.d.ts

@@ -0,0 +1,9 @@
+import type { IconSetConfig } from './build.js';
+export type NanoIconsConfig = {
+    iconSets: IconSetConfig[];
+};
+/**
+ * Load .nanoicons.json from the project root.
+ * Throws with a helpful message if the file is missing or malformed.
+ */
+export declare function loadNanoIconsConfig(projectRoot: string): NanoIconsConfig;

package/lib/commonjs/cli/config.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadNanoIconsConfig = loadNanoIconsConfig;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Load .nanoicons.json from the project root.
+ * Throws with a helpful message if the file is missing or malformed.
+ */
+function loadNanoIconsConfig(projectRoot) {
+    const configPath = node_path_1.default.join(projectRoot, '.nanoicons.json');
+    if (!node_fs_1.default.existsSync(configPath)) {
+        throw new Error(`[react-native-nano-icons] No .nanoicons.json found at project root (${projectRoot}).\n` +
+            `Create one with: { "iconSets": [{ "inputDir": "assets/icons", "fontFamily": "MyIcons" }] }`);
+    }
+    const raw = node_fs_1.default.readFileSync(configPath, 'utf8');
+    const config = JSON.parse(raw);
+    if (!config?.iconSets?.length) {
+        throw new Error(`[react-native-nano-icons] .nanoicons.json must contain an "iconSets" array with at least one entry.`);
+    }
+    return config;
+}

package/lib/commonjs/cli/index.d.ts

@@ -0,0 +1,4 @@
+export { buildAllFonts, type IconSetConfig, type BuiltFont } from './build.js';
+export { createOraLogger, createQuietLogger, detectExpoLogLevel, type NanoLogger, type LogLevel, } from './logger.js';
+export { loadNanoIconsConfig, type NanoIconsConfig } from './config.js';
+export { linkBare } from './link.js';

package/lib/commonjs/cli/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.linkBare = exports.loadNanoIconsConfig = exports.detectExpoLogLevel = exports.createQuietLogger = exports.createOraLogger = exports.buildAllFonts = void 0;
+var build_js_1 = require("./build.js");
+Object.defineProperty(exports, "buildAllFonts", { enumerable: true, get: function () { return build_js_1.buildAllFonts; } });
+var logger_js_1 = require("./logger.js");
+Object.defineProperty(exports, "createOraLogger", { enumerable: true, get: function () { return logger_js_1.createOraLogger; } });
+Object.defineProperty(exports, "createQuietLogger", { enumerable: true, get: function () { return logger_js_1.createQuietLogger; } });
+Object.defineProperty(exports, "detectExpoLogLevel", { enumerable: true, get: function () { return logger_js_1.detectExpoLogLevel; } });
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "loadNanoIconsConfig", { enumerable: true, get: function () { return config_js_1.loadNanoIconsConfig; } });
+var link_js_1 = require("./link.js");
+Object.defineProperty(exports, "linkBare", { enumerable: true, get: function () { return link_js_1.linkBare; } });

package/lib/commonjs/cli/link.d.ts

@@ -0,0 +1,11 @@
+import type { NanoLogger } from './logger.js';
+import type { BuiltFont } from './build.js';
+/**
+ * Link built TTFs into native project directories.
+ *
+ * Handles three cases:
+ *  - Both android/ and ios/ exist → link both platforms
+ *  - Only one platform dir exists → link that platform only
+ *  - Neither exists (e.g. React Native Web) → skip native linking, report output dir
+ */
+export declare function linkBare(projectRoot: string, builtFonts: BuiltFont[], logger: NanoLogger): Promise<void>;

package/lib/commonjs/cli/link.js

@@ -0,0 +1,135 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.linkBare = linkBare;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const plist = __importStar(require("plist"));
+const ANDROID_FONTS_DIR = 'android/app/src/main/assets/fonts';
+const IOS_NANOICONS_FONTS_DIR = 'nanoicons-fonts';
+const IOS_RUN_SCRIPT_PHASE_NAME = 'Copy nanoicons fonts';
+async function linkAndroid(projectRoot, builtFonts) {
+    const androidFontsPath = node_path_1.default.join(projectRoot, ANDROID_FONTS_DIR);
+    node_fs_1.default.mkdirSync(androidFontsPath, { recursive: true });
+    for (const b of builtFonts) {
+        const dest = node_path_1.default.join(androidFontsPath, node_path_1.default.basename(b.ttfPath));
+        node_fs_1.default.copyFileSync(b.ttfPath, dest);
+    }
+}
+async function linkIos(projectRoot, builtFonts) {
+    const iosDir = node_path_1.default.join(projectRoot, 'ios');
+    const appDir = node_fs_1.default
+        .readdirSync(iosDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory())
+        .find((d) => node_fs_1.default.existsSync(node_path_1.default.join(iosDir, d.name, 'Info.plist')));
+    if (!appDir)
+        return;
+    const fontNames = [];
+    const iosFontsStaging = node_path_1.default.join(iosDir, IOS_NANOICONS_FONTS_DIR);
+    node_fs_1.default.mkdirSync(iosFontsStaging, { recursive: true });
+    for (const b of builtFonts) {
+        const name = node_path_1.default.basename(b.ttfPath);
+        fontNames.push(name);
+        node_fs_1.default.copyFileSync(b.ttfPath, node_path_1.default.join(iosFontsStaging, name));
+    }
+    const infoPlistPath = node_path_1.default.join(iosDir, appDir.name, 'Info.plist');
+    const plistContent = node_fs_1.default.readFileSync(infoPlistPath, 'utf8');
+    const obj = plist.parse(plistContent);
+    const existing = Array.isArray(obj['UIAppFonts'])
+        ? obj['UIAppFonts']
+        : [];
+    const merged = [...new Set([...existing, ...fontNames])];
+    const updated = {
+        ...obj,
+        UIAppFonts: merged,
+    };
+    node_fs_1.default.writeFileSync(infoPlistPath, plist.build(updated), 'utf8');
+    const xcodeprojDir = node_fs_1.default
+        .readdirSync(iosDir, { withFileTypes: true })
+        .find((d) => d.name.endsWith('.xcodeproj'));
+    if (xcodeprojDir) {
+        const pbxprojPath = node_path_1.default.join(iosDir, xcodeprojDir.name, 'project.pbxproj');
+        const xcode = require('xcode');
+        const project = xcode.project(pbxprojPath);
+        project.parseSync();
+        const hasPhase = Object.entries(project.hash.project.objects['PBXShellScriptBuildPhase'] ?? {}).some(([, v]) => typeof v === 'object' && v?.name?.includes(IOS_RUN_SCRIPT_PHASE_NAME));
+        if (!hasPhase) {
+            const script = `
+        NANOICONS_DIR="\\\${PROJECT_DIR}/${IOS_NANOICONS_FONTS_DIR}"
+        if [ -d "$NANOICONS_DIR" ]; then
+          cp "$NANOICONS_DIR"/*.ttf "\\\${BUILT_PRODUCTS_DIR}/\\\${UNLOCALIZED_RESOURCES_FOLDER_PATH}/" 2>/dev/null || true
+        fi
+      `;
+            project.addBuildPhase([], 'PBXShellScriptBuildPhase', IOS_RUN_SCRIPT_PHASE_NAME, project.getFirstTarget().uuid, { shellPath: '/bin/sh', shellScript: script });
+            node_fs_1.default.writeFileSync(pbxprojPath, project.writeSync(), 'utf8');
+        }
+    }
+}
+/**
+ * Link built TTFs into native project directories.
+ *
+ * Handles three cases:
+ *  - Both android/ and ios/ exist → link both platforms
+ *  - Only one platform dir exists → link that platform only
+ *  - Neither exists (e.g. React Native Web) → skip native linking, report output dir
+ */
+async function linkBare(projectRoot, builtFonts, logger) {
+    if (!builtFonts.length)
+        return;
+    const hasAndroid = node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, 'android'));
+    const hasIos = node_fs_1.default.existsSync(node_path_1.default.join(projectRoot, 'ios'));
+    if (!hasAndroid && !hasIos) {
+        // React Native Web or other non-native target — just report where fonts landed
+        const outputDirs = [
+            ...new Set(builtFonts.map((b) => node_path_1.default.dirname(b.ttfPath))),
+        ];
+        const rel = node_path_1.default.relative(projectRoot, outputDirs[0] ?? '');
+        logger.info(`No native directories found — fonts saved to ${rel}/  (no native dirs, skipping link)`);
+        return;
+    }
+    const linkedPlatforms = [];
+    if (hasAndroid) {
+        await linkAndroid(projectRoot, builtFonts);
+        linkedPlatforms.push('android');
+    }
+    if (hasIos) {
+        await linkIos(projectRoot, builtFonts);
+        linkedPlatforms.push('ios');
+    }
+    logger.succeed(`Linked fonts → ${linkedPlatforms.join(', ')}`);
+}

package/lib/commonjs/cli/logger.d.ts

@@ -0,0 +1,27 @@
+export type LogLevel = 'normal' | 'verbose';
+export type NanoLogger = {
+    start: (msg: string) => void;
+    update: (msg: string) => void;
+    succeed: (msg: string) => void;
+    fail: (msg: string) => void;
+    /** Only printed when level is 'verbose'. */
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+};
+/**
+ * Create an ora spinner-backed logger.
+ * ora and chalk are ESM-only so they are loaded via dynamic import;
+ * this factory must be awaited once before use.
+ */
+export declare function createOraLogger(level: LogLevel): Promise<NanoLogger>;
+/**
+ * Create a plain-text logger suitable for Expo prebuild context.
+ * No ora spinner — only success/error lines are printed to avoid
+ * disrupting Expo's own output.
+ */
+export declare function createQuietLogger(level: LogLevel): Promise<NanoLogger>;
+/**
+ * Infer log level from the Expo CLI environment.
+ * Expo uses EXPO_DEBUG=1 for verbose/debug output.
+ */
+export declare function detectExpoLogLevel(): LogLevel;

package/lib/commonjs/cli/logger.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOraLogger = createOraLogger;
+exports.createQuietLogger = createQuietLogger;
+exports.detectExpoLogLevel = detectExpoLogLevel;
+const PREFIX = 'react-native-nano-icons';
+/**
+ * Create an ora spinner-backed logger.
+ * ora and chalk are ESM-only so they are loaded via dynamic import;
+ * this factory must be awaited once before use.
+ */
+async function createOraLogger(level) {
+    const [{ default: ora }, { default: chalk }] = await Promise.all([
+        import('ora'),
+        import('chalk'),
+    ]);
+    const spinner = ora({ prefixText: `🔬 ${chalk.dim(PREFIX)}` });
+    const dimPrefix = chalk.dim(`  ℹ  `);
+    return {
+        start(msg) {
+            spinner.start(msg);
+        },
+        update(msg) {
+            spinner.text = msg;
+        },
+        succeed(msg) {
+            spinner.succeed(msg);
+        },
+        fail(msg) {
+            spinner.fail(chalk.red(msg));
+        },
+        info(msg) {
+            if (level === 'verbose') {
+                // Print below the current spinner without disrupting it
+                process.stdout.write(`\n${dimPrefix}${chalk.dim(msg)}`);
+            }
+        },
+        warn(msg) {
+            spinner.warn(chalk.yellow(msg));
+        },
+    };
+}
+/**
+ * Create a plain-text logger suitable for Expo prebuild context.
+ * No ora spinner — only success/error lines are printed to avoid
+ * disrupting Expo's own output.
+ */
+async function createQuietLogger(level) {
+    const { default: chalk } = await import('chalk');
+    const dimPrefix = `🔬 ${chalk.dim(PREFIX)}`;
+    const tick = chalk.green('✓');
+    const cross = chalk.red('✗');
+    const info = chalk.blue('ℹ');
+    const warning = chalk.yellow('⚠');
+    return {
+        start(_msg) {
+            /* no-op */
+        },
+        update(_msg) {
+            /* no-op */
+        },
+        succeed(msg) {
+            console.log(`${dimPrefix} ${tick} ${msg}`);
+        },
+        fail(msg) {
+            console.error(`${dimPrefix} ${cross} ${msg}`);
+        },
+        info(msg) {
+            if (level === 'verbose')
+                console.log(`${dimPrefix} ${info} ${msg}`);
+        },
+        warn(msg) {
+            console.warn(`${dimPrefix} ${warning} ${msg}`);
+        },
+    };
+}
+/**
+ * Infer log level from the Expo CLI environment.
+ * Expo uses EXPO_DEBUG=1 for verbose/debug output.
+ */
+function detectExpoLogLevel() {
+    return process.env['EXPO_DEBUG'] ? 'verbose' : 'normal';
+}

package/lib/commonjs/index.node.js

@@ -0,0 +1,8 @@
+"use strict";
+const createNanoIconSet = (...args) => {
+    const { createIconSet } = require('./createNanoIconsSet');
+    return createIconSet(...args);
+};
+const plugin = require('./plugin/src/index')
+    .default;
+module.exports = Object.assign(plugin, { createNanoIconSet });

package/lib/commonjs/plugin/src/buildFonts.d.ts

@@ -0,0 +1,7 @@
+import type { IconSetConfig, BuiltFont } from './types.js';
+/**
+ * Build TTF + glyphmap for all icon sets.
+ * Shows an ora spinner per font set; catches errors and displays a friendly message
+ * unless EXPO_DEBUG is set, in which case the full error is re-thrown.
+ */
+export declare function buildAllFonts(iconSets: IconSetConfig[], projectRoot: string): Promise<BuiltFont[]>;

package/lib/commonjs/plugin/src/buildFonts.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAllFonts = buildAllFonts;
+const index_js_1 = require("../../cli/index.js");
+/**
+ * Build TTF + glyphmap for all icon sets.
+ * Shows an ora spinner per font set; catches errors and displays a friendly message
+ * unless EXPO_DEBUG is set, in which case the full error is re-thrown.
+ */
+async function buildAllFonts(iconSets, projectRoot) {
+    const level = (0, index_js_1.detectExpoLogLevel)();
+    const logger = await (0, index_js_1.createQuietLogger)(level);
+    try {
+        return await (0, index_js_1.buildAllFonts)(iconSets, projectRoot, { logger });
+    }
+    catch (err) {
+        if (level === 'verbose') {
+            throw err;
+        }
+        logger.fail('Error optimizing icons. Run with EXPO_DEBUG=1 for more logs.');
+        return [];
+    }
+}