Migration Tool
Troubleshooting

Troubleshooting

Common issues and solutions when using the migration tool.

Icon Not Found

Problem

Some icons don't have a direct mapping and the original import is kept.

Solution

Check the migration report for unmapped icons. You can:

  1. Search for alternatives - Visit hugeicons.com (opens in a new tab) to find similar icons
  2. Keep the original - The CLI preserves unmapped icons, so your app won't break
  3. Manual mapping - Replace the icon manually after migration

Example

If MyCustomIcon isn't mapped:

// The CLI keeps the original
import { MyCustomIcon } from "lucide-react";
 
// You can manually replace it later
import { HugeiconsIcon } from "@hugeicons/react";
import { CustomIcon } from "@hugeicons/core-free-icons";
 
<HugeiconsIcon icon={CustomIcon} />

Type Errors After Migration

Problem

Some complex TypeScript patterns may need manual adjustment.

Solution

Common fixes for type errors:

Icon prop types:

import { type IconSvgElement } from "@hugeicons/react";
 
interface Props {
  icon: IconSvgElement;
}

Component props:

import { type HugeiconsIcon } from "@hugeicons/react";
 
// For icon props
type IconProps = React.ComponentProps<typeof HugeiconsIcon>;
 
// For icon prop without the icon itself
type IconStyleProps = Omit<IconProps, "icon">;

Generic icon components:

interface ButtonProps {
  icon?: IconSvgElement;
  label: string;
}
 
function Button({ icon, label }: ButtonProps) {
  return (
    <button>
      {icon && <HugeiconsIcon icon={icon} size={20} />}
      {label}
    </button>
  );
}

Dynamic Icon Rendering

Problem

Code with dynamic icon selection like <item.icon /> needs special handling.

How the CLI Handles It

The CLI automatically wraps dynamic icon patterns:

Before:

{items.map((item) => (
  <div key={item.id}>
    {item.icon && <item.icon />}
  </div>
))}

After:

{items.map((item) => (
  <div key={item.id}>
    {item.icon && <HugeiconsIcon icon={item.icon} />}
  </div>
))}

Manual Adjustment

If you have complex dynamic rendering, you may need to adjust:

// If you store icons in an object
const iconMap = {
  home: Home01Icon,
  settings: Settings01Icon,
  user: UserIcon,
};
 
// Render dynamically
<HugeiconsIcon icon={iconMap[iconName]} />

Package Installation Issues

Problem

The CLI fails to install Hugeicons packages.

Solutions

Check Node.js version:

node --version
# Should be >= 18.0.0

Clear package manager cache:

# npm
npm cache clean --force
 
# pnpm
pnpm store prune
 
# yarn
yarn cache clean

Manual installation:

npm install @hugeicons/react @hugeicons/core-free-icons
# or
pnpm add @hugeicons/react @hugeicons/core-free-icons
# or
yarn add @hugeicons/react @hugeicons/core-free-icons

Pro Icons Configuration

Problem

Pro icons aren't loading after migration.

Solution

Ensure your registry configuration is correct:

For npm/pnpm (.npmrc):

@hugeicons-pro:registry=https://npm.hugeicons.com/
//npm.hugeicons.com/:_authToken=UNIVERSAL_LICENSE_KEY

Build Errors After Migration

Problem

Build fails with module not found errors.

Solutions

1. Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

2. Check imports: Ensure you're importing from the correct packages:

// ✅ Correct
import { HugeiconsIcon } from "@hugeicons/react";
import { Home01Icon } from "@hugeicons/core-free-icons";
 
// ❌ Wrong
import { Home01Icon } from "@hugeicons/react";

3. Update TypeScript config: Add to your tsconfig.json if needed:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Backup and Rollback

Problem

Something went wrong and you need to revert changes.

Solution

Use the built-in revert command:

npx @hugeicons/migrate revert ./my-project

This will:

  1. Show available backups
  2. Let you select which backup to restore
  3. Restore all files from that backup

Manual rollback: If the revert command doesn't work, backups are stored in:

<project-path>/.hugeicons-migration-backups/

You can manually copy files from there.

Still Having Issues?

If you're still experiencing problems:

  1. Check the migration report - It contains detailed warnings and suggestions
  2. Review your code - Some edge cases may need manual fixes
  3. Contact support - Reach out to us at Discord (opens in a new tab) or [email protected]

Please provide:

  • Migration report
  • Error messages
  • Project setup (React version, TypeScript config, etc.)
CommandsQuick Start