Overview

Migrate your project from popular icon libraries to Hugeicons with ease
Migrating from icon libraries like Font Awesome, Lucide, or Heroicons is often a confusing and heavy task in real codebases. Icons are spread across components, imported in different patterns, and tightly coupled to UI logic. We built @hugeicons/migrate to handle this safely. This CLI tool scans your project, detects existing usage, and maps icons to their Hugeicons equivalents with built-in preview, backup, and rollback support making it suitable for production-grade React applications.

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

Simply run the CLI without arguments to enter interactive mode.

Or install it globally:

npm install -g @hugeicons/migrate

Supported Libraries

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:

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:

Next Steps

• Quick Start - Get started with the migration tool
• Commands - Detailed command reference
• Troubleshooting - Common issues and solutions