Documentation

iconcodegen

Complete command reference for setting up and maintaining your icon library.

Initialize

terminal

npx iconcodegen init

Asks for your save path and provider, then writes an iconcodegen.json to your project root.

iconcodegen.json

{
  "savePath": "./src/components/icons",
  "provider": "iconify",
  "iconNamePattern": "{name}Icon"
}

Run the dashboard

terminal

npx iconcodegen

Spins up the local visual dashboard at http://127.0.0.1:3000 to instantly search and generate typed React icons.

If port 3000 is busy, the server automatically tries 3001, 3002, and so on.

Day-2 commands

terminal

npx iconcodegen prune

Removes barrel-file exports pointing to icons you've deleted manually.

output

🔍 Scanning ./src/components/icons for barrel files...
🗑️  [DRY RUN] Would remove dangling export: AirplayIcon (file not found)
🗑️  [DRY RUN] Would remove dangling export: CustomThing (file not found)
✅ Dry run complete. Found 2 missing export(s) to remove.

terminal

npx iconcodegen audit

Reports icons that aren't imported anywhere in your code. Read-only — never deletes anything.

output

🔍 Scanning ./src for imported icons...
📦 Found 6 total icons in ./src/components/icons
✅ Found 1 explicitly imported in your code.

⚠️  5 icons found with no direct static import detected.
Please verify manually before removing, especially if you use dynamic selection.

  ⚠️  IMPORTANT: This scanner only matches import paths containing the
  literal string "icons" (e.g. '@/components/icons', '../icons'). If
  your project imports icons through an alias that does NOT contain
  that word (e.g. '@/ui/svg-pack'), this tool cannot see those imports
  and WILL incorrectly list those icons as unused. If you use custom
  path aliases, verify manually — do not trust this report blindly.

[LIMITATIONS] The scanner ONLY detects static named imports:
  ✅ Detects: import { ArrowIcon } from '@/icons'
  ❌ Ignores: import * as Icons from '@/icons' (Wildcards)
  ❌ Ignores: import(iconName) (Dynamic Imports)
  ❌ Ignores: Re-exported barrel chains across monorepo boundaries

To manually remove these 5 potentially unused icons, review and run:

  rm ./src/components/icons/ActivityIcon.tsx \
     ./src/components/icons/AirplayIcon.tsx \
     ./src/components/icons/AlarmCheckIcon.tsx \
     ./src/components/icons/CameraIcon.tsx \
     ./src/components/icons/CheckIcon.tsx

terminal

npx iconcodegen sync

Renames existing icons to match a naming pattern you've changed in config. Safe — supports --dry-run and blocks anything it's unsure about.

output

Iconcodegen Sync
--------------------------------------------------
[RENAME]     ActivityIcon.tsx → SuperActivity.tsx
[RENAME]     AlarmCheckIcon.tsx → SuperAlarmCheck.tsx
[RENAME]     AnotherHome.tsx → SuperHome.tsx
[RENAME]     AppBell.tsx → SuperBell.tsx
[INDEX]      Rewrote 4 export(s) in index.ts
[COLLISION]  CameraIcon.tsx (Target SuperCamera.tsx already exists)
[BLOCKED]    CheckIcon.tsx (Manual or aliased export reference found in index.ts)
[DUPLICATE]  HomeIcon.tsx (Shares metadata with another file)
--------------------------------------------------
Summary: 4 Rename, 1 Collision, 1 Blocked, 1 Duplicate, 0 Unsupported, 0 Keep

Providers

The provider field in your config controls which icon backend is used.

iconifyDefault

Fetches SVGs on demand from the public Iconify API — zero local dependencies required. Supports 11 curated icon packs: mdi, ph, lucide, heroicons, bi, tabler, radix-icons, feather, ri, carbon, ion.

iconcodegen.json

{
  "provider": "iconify"
}

untitled-uiRequires @untitledui-pro/icons

Renders icons fully offline using your locally installed @untitledui-pro/icons package. Scans all 4 style categories (line, solid, duotone, duocolor) and indexes them on startup. No external requests — ever.

iconcodegen.json

{
  "provider": "untitled-ui"
}

Config reference

iconcodegen.json

{
  "savePath": "./src/components/icons",   // Where generated components are saved
  "provider": "iconify",                  // Backend: "iconify" or "untitled-ui"
  "iconNamePattern": "{name}Icon"         // Enforces strict naming (e.g. "{name}Icon")
}

Flags

Flag	Description	Supported by
--dry-run	Previews changes without touching any files.	prune, sync
--target	Overrides the source code directory to scan.	audit
--port	Changes the dashboard server port.	(default start)
--headless	Starts the server without opening the browser.	(default start)