Overview

@hugeicons/migrate is a powerful CLI tool that helps you migrate your React projects from popular icon libraries (Lucide, FontAwesome, Heroicons, Feather, Tabler, Phosphor) to Hugeicons — 46,000+ icons across 10 styles.

Features

• 🔍 Smart Detection - Automatically detects icon libraries used in your project
• 📊 Detailed Planning - Preview all changes before applying them
• 🔄 Safe Migration - Creates automatic backups before making changes
• ↩️ Easy Rollback - Revert changes anytime with built-in restore
• 📝 HTML Reports - Generate beautiful migration reports
• 🎨 Style Support - Choose between Free and Pro icon styles
• 📦 Auto Install - Automatically installs required Hugeicons packages

Installation

You can run the migration tool directly using npx:

npx @hugeicons/migrate

Or install it globally:

npm install -g @hugeicons/migrate

Quick Start

Interactive Mode

Simply run the CLI without arguments to enter interactive mode:

npx @hugeicons/migrate

This will:

1. Display a welcome message
2. Detect or let you choose the project folder
3. Present available commands (scan, plan, apply, revert)

Command Line Mode

You can also run specific commands directly:

# Scan your project for icon usage
npx @hugeicons/migrate scan ./my-project

# Generate a migration plan
npx @hugeicons/migrate plan ./my-project

# Preview changes (dry run)
npx @hugeicons/migrate apply ./my-project

# Apply changes
npx @hugeicons/migrate apply ./my-project --write

# Revert to backup
npx @hugeicons/migrate revert ./my-project

Commands

scan

Scans your project to detect icon libraries and their usage.

npx @hugeicons/migrate scan <project-path>

Output includes:

• Detected icon libraries (Lucide, FontAwesome, Heroicons, Feather, Tabler, Phosphor)
• Number of icon usages per library
• Files containing icons

plan

Generates a detailed migration plan showing what will change.

npx @hugeicons/migrate plan <project-path>

Output includes:

• Icon mapping (old → new)
• Files that will be modified
• Required Hugeicons packages

apply

Applies the migration to your project.

# Dry run (preview changes)
npx @hugeicons/migrate apply <project-path>

# Apply changes
npx @hugeicons/migrate apply <project-path> --write

Options:

• --write - Actually apply the changes (without this, it's a dry run)
• --style <style> - Icon style: free or pro (default: free)
• --report - Generate an HTML report after migration

revert

Restores your project from a backup created during migration.

npx @hugeicons/migrate revert <project-path>

Lists available backups and lets you choose which one to restore.

Supported Libraries

| Library | Package | Status | |---------|---------|--------| | Lucide React | lucide-react | ✅ Fully Supported | | FontAwesome | @fortawesome/react-fontawesome, @fortawesome/free-solid-svg-icons, etc. | ✅ Fully Supported | | Heroicons | @heroicons/react | ✅ Fully Supported | | Feather Icons | react-feather, feather-icons-react | ✅ Fully Supported | | Tabler Icons | @tabler/icons-react | ✅ Fully Supported | | Phosphor Icons | @phosphor-icons/react, phosphor-react | ✅ Fully Supported |

Each library uses curated mapping files (70–90% coverage) plus fuzzy matching for unmapped icons, so migrations produce real Hugeicons icon names.

How It Works

1. Detection

The CLI scans your project for import statements from supported icon libraries:

// Lucide / Heroicons / Feather / Tabler / Phosphor (direct components)
import { Home, Settings, User } from "lucide-react";
import { HomeIcon, UserIcon } from "@heroicons/react/24/solid";
import { IconHome, IconUser } from "@tabler/icons-react";
import { House, User } from "@phosphor-icons/react";

// FontAwesome (wrapper component)
import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
import { faHome, faUser } from "@fortawesome/free-solid-svg-icons";

2. Mapping

Icons are mapped to their Hugeicons equivalents using our comprehensive mapping database:

| Lucide | Hugeicons | |--------|-----------| | Home | Home01Icon | | Settings | Settings01Icon | | User | User01Icon |

3. Transformation

The code is transformed to use Hugeicons:

// After (Lucide / Heroicons / Feather / Tabler / Phosphor)
import { HugeiconsIcon } from "@hugeicons/react";
import { Home01Icon, Settings01Icon, UserIcon } from "@hugeicons/core-free-icons";

<HugeiconsIcon icon={Home01Icon} size={24} />

// After (FontAwesome: <FontAwesomeIcon icon={faUser} /> → Hugeicons)
<HugeiconsIcon icon={UserIcon} size={24} />

4. Type Handling

TypeScript types are automatically updated:

| Before | After | |--------|-------| | LucideIcon | IconSvgElement | | React.ComponentProps<"svg"> | Omit<React.ComponentProps<typeof HugeiconsIcon>, "icon"> |

Configuration

Using Pro Icons

For Pro icons, you'll need a Hugeicons license. The CLI will prompt for your license key and configure the appropriate registry settings:

npx @hugeicons/migrate apply ./my-project --style pro --write

The CLI automatically creates the correct configuration file based on your package manager:

| Package Manager | Config File | |-----------------|-------------| | npm | .npmrc | | pnpm | .npmrc | | yarn (v2+) | .yarnrc.yml | | bun | bunfig.toml |

Migration Report

After applying changes with --write, an HTML report is generated showing:

• Summary statistics
• Source library detected
• List of modified files
• Icon mappings (old → new)
• Any warnings or manual steps needed

The report automatically opens in your default browser.

Best Practices

1. Always backup first - While the CLI creates automatic backups, consider committing your changes to git before migration

2. Review the plan - Run plan before apply to understand what will change

3. Start with dry run - Run apply without --write first to preview changes

4. Test after migration - Run your project's tests and linter after migration

5. Check TypeScript errors - Some edge cases may need manual fixes

Troubleshooting

Icon not found

If an icon doesn't have a direct mapping, the original import is kept. Check the migration report for unmapped icons.

Type errors after migration

Some complex TypeScript patterns may need manual adjustment. Common fixes:

// If you see type errors with icon props, use:
import { type IconSvgElement } from "@hugeicons/react";

interface Props {
  icon: IconSvgElement;
}

Dynamic icon rendering

The CLI handles patterns like <item.icon /> by wrapping them:

// Before
{item.icon && <item.icon />}

// After
{item.icon && <HugeiconsIcon icon={item.icon} />}

Requirements

• Node.js >= 18.0.0
• React project with TypeScript or JavaScript
• Supported icon library installed

Links

• Hugeicons - Browse 46,000+ icons across 10 styles
• Documentation
• Icon Search
• GitHub

License

MIT © Hugeicons