Skip to Content
Migration ToolQuick Start

Quick Start

Get started with the Hugeicons migration tool in just a few steps.

Requirements

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

Interactive Mode

Simply run the CLI without arguments to enter interactive mode:

npx @hugeicons/migrate

The CLI will guide you through the migration process with interactive prompts:

? Select project:
  ❯ Use current project

? What would you like to do?
  ❯ Plan - Generate migration plan with icon mappings

? Select Hugeicons style:
  ❯ Stroke Rounded (free)

You can see the generated plan

? What would you like to do next?
  ❯ Apply - Write changes to files

? Use previous style (stroke)?
  ❯ Yes, use stroke

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

Step-by-Step Migration

Follow these steps for a safe migration:

Step 1: Scan Your Project

First, scan your project to see which icon libraries are detected:

npx @hugeicons/migrate scan ./my-project

This will show:

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

Step 2: Generate a Migration Plan

Review what changes will be made:

npx @hugeicons/migrate plan ./my-project

The plan shows:

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

Step 3: Preview Changes (Dry Run)

Before making any changes, do a dry run:

npx @hugeicons/migrate apply ./my-project

This shows exactly what will change without modifying any files.

Step 4: Apply the Migration

When you’re ready, apply the changes:

npx @hugeicons/migrate apply ./my-project --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

Step 5: Review and Test

After migration:

  1. Review the generated HTML report (opens automatically)
  2. Run your tests
  3. Check for TypeScript errors
  4. Verify the app works as expected

Using Pro Icons

For Pro icons, you’ll need a Hugeicons license. The CLI will prompt for your license key:

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

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

Package ManagerConfig File
npm.npmrc
pnpm.npmrc
yarn (v2+).yarnrc.yml
bunbunfig.toml

The CLI writes your license key into that file literally, and it doesn’t touch .gitignore. Don’t commit the file as written. Once the migration is done, replace the key with the ${HUGEICONS_LICENSE_KEY} placeholder and set the environment variable instead. See Activate License. If the key has already been committed, have it rotated.

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

Next Steps

OverviewCommands