hugeicons-cli

Interactive CLI for managing HugeIcons icon exports. Generates tree-shakeable barrel files so you only bundle the icons you use.

Works with both the free (@hugeicons/core-free-icons — 5,100+ stroke-rounded icons) and Pro (@hugeicons-pro/* — 27,000+ icons in 9 styles) packages.

Why This Exists

If you're working with React Native (or any JS app) and using HugeIcons, you've probably noticed something painful: importing icons the "normal" way destroys your bundle size.

// Looks innocent, right?
import { Notification03Icon } from '@hugeicons/core-free-icons';

That single import pulls in the entire package — roughly 5 MB of static icon data per variant. With the Pro license you get 9 variant packages. That's potentially 45+ MB of icons baked into your app, even if you only use 30 of them.

The fix is to import each icon individually from its ESM path:

export { default as Alert01IconStroke } from "@hugeicons-pro/core-stroke-rounded/dist/esm/Alert01Icon";
export { default as Alert01IconDuotone } from "@hugeicons-pro/core-duotone-rounded/dist/esm/Alert01Icon";
export { default as AlertCircleIcon } from "@hugeicons-pro/core-stroke-rounded/dist/esm/AlertCircleIcon";

This approach is tree-shakeable — your bundler only includes the icons you actually reference. But maintaining this file by hand is tedious. You have to remember the exact file path, pick a consistent alias name, check which variants exist, and avoid duplicates. I kept wasting time on it. LLMs help, but when you need to browse different styles and variants visually, it's faster to do it yourself.

So I built this CLI. It lets you search, pick, and add icons interactively — with auto-naming, conflict detection, and a validator to catch broken imports after package upgrades.

Important Notice

This tool does not include, distribute, or pirate any icons. It only generates export/require statements that reference officially published HugeIcons packages installed in your own project.

• Free icons (@hugeicons/core-free-icons) are open to use in any project at no cost.
• Pro icons (@hugeicons-pro/*) require a valid HugeIcons Pro license.

Install

# Global
npm install -g hugeicons-cli

# Or run directly
npx hugeicons-cli init

# Or as a dev dependency in your project
npm install -D hugeicons-cli

Quick Start

# 1. Initialize config (auto-detects your project structure)
hugeicons init

# 2. Add icons interactively
hugeicons add Search       # fuzzy search → select icons → pick variants → confirm
hugeicons add Calendar     # finds Calendar01-05, CalendarAdd, CalendarBlock, etc.
hugeicons add              # opens interactive search (type to filter 5,000+ icons)

# 3. Validate your icon file for broken imports
hugeicons validate

How It Works

HugeIcons packages ship thousands of individual ES module files. Importing directly from these packages leads to long, hard-to-manage import paths:

// Without hugeicons-cli — scattered, verbose imports
import Search01Icon from "@hugeicons-pro/core-stroke-rounded/dist/esm/Search01Icon";
import Search01IconSolid from "@hugeicons-pro/core-solid-rounded/dist/esm/Search01Icon";

hugeicons-cli generates a single barrel file that re-exports only the icons you use:

// Generated by hugeicons-cli — clean, tree-shakeable
export { default as Search01IconStroke } from "@hugeicons-pro/core-stroke-rounded/dist/esm/Search01Icon";
export { default as Search01IconSolid } from "@hugeicons-pro/core-solid-rounded/dist/esm/Search01Icon";

Then in your components:

import { Search01IconStroke, Search01IconSolid } from "@/icons/hugeicons";

Commands

hugeicons init

Interactive setup that creates .hugeiconrc.json in your project root.

• Auto-detects your framework (React Native, Next.js, React)
• Scans your project file structure to suggest the best location for the barrel file
• Finds installed @hugeicons/core-free-icons and @hugeicons-pro/* packages
• Lets you choose naming convention and module format (ESM/CJS)
• Tracks package version for migration detection

What the init wizard asks:

1. Target file — where to write icon exports (suggested based on your project structure)
2. Module format — ESM (export { default as ... }) or CJS (module.exports.X = require(...))
3. Packages — which icon packages to use (auto-detects installed ones)
4. Naming — how to name export aliases (short, full, or minimal)

hugeicons add [search]

Add icons interactively:

1. Fuzzy search — type a partial name to find matching icons across all configured packages
2. Clickable URLs — each result shows a link to hugeicons.com so you can visually compare styles before picking (cmd/ctrl+click in most terminals)
3. Multi-select — pick which icons to add (e.g., Search01Icon and Search02Icon)
4. Variant picker — choose one or more styles (stroke, solid, duotone, bulk, etc.) with per-variant URLs for visual comparison
5. Auto-naming — generates consistent alias names based on your naming config
6. Conflict detection — warns if an alias already exists with a different import
7. Preview & confirm — see exactly what will be written before saving

Example session

$ hugeicons add Star

Found 8 icon(s) matching "Star":

  Browse on hugeicons.com (cmd/ctrl+click):
    StarIcon            https://hugeicons.com/icon/star?style=stroke-rounded
    StarCircleIcon      https://hugeicons.com/icon/star-circle?style=stroke-rounded
    StarFaceIcon        https://hugeicons.com/icon/star-face?style=stroke-rounded
    StarHalfIcon        https://hugeicons.com/icon/star-half?style=stroke-rounded
    ...

? Select icons to add (8 found):
  ◉ StarIcon
  ◉ StarCircleIcon
  ○ StarFaceIcon
  ○ StarHalfIcon
  ...

    stroke-rounded      https://hugeicons.com/icon/star?style=stroke-rounded
    duotone-rounded     https://hugeicons.com/icon/star?style=duotone-rounded
    solid-rounded       https://hugeicons.com/icon/star?style=solid-rounded

? Apply the same variant(s) to all selected icons? Yes

? Select variant(s):
  ◉ stroke-rounded
  ◉ duotone-rounded

Will add 4 export(s):

  export { default as StarCircleIconDuotone } from "@hugeicons-pro/core-duotone-rounded/dist/esm/StarCircleIcon";
  export { default as StarCircleIconStroke } from "@hugeicons-pro/core-stroke-rounded/dist/esm/StarCircleIcon";
  export { default as StarIconDuotone } from "@hugeicons-pro/core-duotone-rounded/dist/esm/StarIcon";
  export { default as StarIconStroke } from "@hugeicons-pro/core-stroke-rounded/dist/esm/StarIcon";

? Confirm? Yes

  Added 4 export(s) to src/icons/hugeicons.ts

hugeicons validate

Checks your generated icon file for issues:

• Broken imports — icon file doesn't exist in node_modules (renamed/removed after a package upgrade)
• Duplicate aliases — same export name used for different icons
• Malformed lines — lines that don't match the expected export pattern

Returns exit code 1 if any issues are found — use in CI pipelines.

$ hugeicons validate

Validating src/icons/hugeicons.ts...

✗ 2 broken import(s):
  L14: Calendar02IconBulk → @hugeicons-pro/core-bulk-rounded/dist/esm/Calendar02Icon
    File not found: node_modules/@hugeicons-pro/core-bulk-rounded/dist/esm/Calendar02Icon.js

⚠ 1 duplicate alias(es):
  "StarIcon" defined 2 times:
    L80: export { default as StarIcon } from "@hugeicons-pro/core-stroke-rounded/dist/esm/StarIcon";
    L81: export { default as StarIcon } from "@hugeicons-pro/core-duotone-rounded/dist/esm/StarIcon";

97/99 valid, 2 broken, 1 duplicate alias(es), 0 malformed

Config (.hugeiconrc.json)

{
  "targetFile": "src/icons/hugeicons.ts",
  "moduleType": "esm",
  "packages": [
    "free",
    "stroke-rounded",
    "solid-rounded",
    "duotone-rounded"
  ],
  "naming": "short",
  "packageVersion": "4.0.0"
}

Naming Conventions

| Convention | Example | Best for | |-----------|---------|----------| | short | StarIconStroke, StarIconSolid | Most projects (default). Drops the shape since most use "rounded". | | full | StarIconStrokeRounded, StarIconSolidSharp | When mixing shapes (e.g., both rounded and sharp variants). | | minimal | StarIcon | Single variant per icon only. Falls back to short when multiple variants of the same icon are added. |

Supported Packages

| Variant | Package | License | |---------|---------|---------| | free | @hugeicons/core-free-icons | Free (5,100+ stroke-rounded icons) | | bulk-rounded | @hugeicons-pro/core-bulk-rounded | Pro | | duotone-rounded | @hugeicons-pro/core-duotone-rounded | Pro | | solid-rounded | @hugeicons-pro/core-solid-rounded | Pro | | solid-sharp | @hugeicons-pro/core-solid-sharp | Pro | | solid-standard | @hugeicons-pro/core-solid-standard | Pro | | stroke-rounded | @hugeicons-pro/core-stroke-rounded | Pro | | stroke-sharp | @hugeicons-pro/core-stroke-sharp | Pro | | stroke-standard | @hugeicons-pro/core-stroke-standard | Pro | | twotone-rounded | @hugeicons-pro/core-twotone-rounded | Pro |

Version Migration

The config tracks your installed @hugeicons-pro package version. When you upgrade:

1. hugeicons add detects the version change and warns you
2. Run hugeicons validate to find any broken imports
3. Fix or re-add renamed/removed icons

Add hugeicons validate to your CI pipeline to catch issues automatically.

Project Structure Detection

During hugeicons init, the CLI analyzes your project to suggest the best location:

| Framework | Detected by | Suggested path | |-----------|------------|----------------| | React Native | react-native in deps | src/icons/hugeicons.ts | | Next.js | next in deps | src/components/icons.ts | | React | react in deps | src/icons/hugeicons.ts |

It also checks for existing icon files (src/icons/, src/components/icons.tsx, etc.) and suggests those if found.

Contributing

# Clone and install
git clone <repo-url>
cd hugeicons-cli
npm install

# Development
npm run dev          # Watch mode (TypeScript)
npm run build        # Build once
npm run typecheck    # Type check without emitting
npm run lint         # Lint with Biome
npm run lint:fix     # Auto-fix lint issues
npm run format       # Format with Biome

PS: Disable Linting on Your Icon File

The generated barrel file is machine-managed — there's no reason to lint or format it. It will have long import paths, inconsistent quotes depending on when lines were added, and your import organizer will constantly want to rearrange it. Save yourself the noise and exclude it.

ESLint — .eslintignore or eslintConfig in package.json:

src/icons/hugeicons.ts

Biome — biome.json:

{
  "files": {
    "ignore": ["src/icons/hugeicons.ts"]
  }
}

Prettier — .prettierignore:

src/icons/hugeicons.ts

Use hugeicons validate instead — it catches the things that actually matter (broken imports, duplicates) without fighting your formatter.

License

MIT — see LICENSE.

This tool is not affiliated with or endorsed by HugeIcons. HugeIcons and HugeIcons Pro are trademarks of their respective owners.