npm package: @hugeicons/migrate
Description: CLI tool to migrate from popular icon libraries (Lucide, Heroicons, FontAwesome) to Hugeicons
Author: Hugeicons
Latest version: 0.1.4

<p align="center">
  <a href="https://hugeicons.com">
    <img src="https://hugeicons.com/assets/logo.svg" alt="Hugeicons" width="200" />
  </a>
</p>

<h1 align="center">@hugeicons/migrate</h1>

<p align="center">
  <strong>Migrate your project from popular icon libraries to Hugeicons with ease</strong>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@hugeicons/migrate"><img src="https://img.shields.io/npm/v/@hugeicons/migrate.svg" alt="npm version" /></a>
  <a href="https://www.npmjs.com/package/@hugeicons/migrate"><img src="https://img.shields.io/npm/dm/@hugeicons/migrate.svg" alt="npm downloads" /></a>
  <a href="https://github.com/hugeicons/migrate/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@hugeicons/migrate.svg" alt="license" /></a>
</p>

---

## 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](https://hugeicons.com) — 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`:

```bash
npx @hugeicons/migrate
```

Or install it globally:

```bash
npm install -g @hugeicons/migrate
```

## Quick Start

### Interactive Mode

Simply run the CLI without arguments to enter interactive mode:

```bash
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:

```bash
# 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.

```bash
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.

```bash
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.

```bash
# 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.

```bash
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:

```typescript
// 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:

```typescript
// 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:

```bash
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:

```typescript
// 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:

```typescript
// 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](https://hugeicons.com) - Browse 46,000+ icons across 10 styles
- [Documentation](https://hugeicons.com/docs)
- [Icon Search](https://hugeicons.com/icons)
- [GitHub](https://github.com/hugeicons/migrate)

## License

MIT © [Hugeicons](https://hugeicons.com)