Overview

@hugeicons/migrate is a powerful CLI tool that helps you migrate your React projects from popular icon libraries like Lucide, Heroicons, and FontAwesome to Hugeicons — the world's largest icon library with 36,000+ icons.

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, Heroicons, FontAwesome, etc.)
• 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 | Status | |---------|--------| | Lucide React | ✅ Fully Supported | | Heroicons | 🚧 Coming Soon | | FontAwesome | 🚧 Coming Soon | | Feather Icons | 🚧 Coming Soon | | Phosphor Icons | 🚧 Coming Soon |

How It Works

1. Detection

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

// Before
import { Home, Settings, User } from "lucide-react";

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
import { HugeiconsIcon } from "@hugeicons/react";
import { Home01Icon, Settings01Icon, User01Icon } from "@hugeicons/core-free-icons";

// Usage
<HugeiconsIcon icon={Home01Icon} 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 36,000+ icons
• Documentation
• Icon Search
• GitHub

License

MIT © Hugeicons