Hugeicons Flux Laravel Package

Getting Started

Minimal Steps

1. Install the package (PHP 8.3+ required):

   composer require abduns/hugeicons-flux
   

2. Publish the Laravel Boost skill (optional):

   php artisan hugeicons:boost-skill
   

3. Use a free icon in Blade:

   <flux:icon.hugeicons.home-01 class="size-8" />
   

   • Replace home-01 with any kebab-cased Hugeicons icon name (e.g., search-02).

First Use Case

Replace placeholder icons in Flux components:

<flux:button icon="hugeicons.home-01" />

• No configuration needed for free icons (5,100+ Stroke Rounded styles included).
• Zero runtime cost—icons are statically compiled.

Where to Look First

• Icon naming: Verify names via Hugeicons’ free set (e.g., Home01Icon → home-01).
• Blade usage: Icons are registered under flux:icon.hugeicons.*.
• Pro setup: Skip unless needing specific styles (see Advanced Usage).

Implementation Patterns

Core Workflows

1. Basic Icon Usage

<flux:icon.hugeicons.search-01 class="size-6 text-gray-500" />

• Flux integration:

  <flux:button icon="hugeicons.calendar-03" />
  <flux:navlist.item icon="hugeicons.dashboard-square-01">Dashboard</flux:navlist.item>
  

2. Variant Customization

<flux:icon.hugeicons.search-01 variant="solid-rounded" class="size-8" />

3. Pro Icons Workflow

1. Install Pro packages (e.g., for solid-rounded):

   npm install --save-optional @hugeicons-pro/core-solid-rounded
   

2. Generate icons:

   php artisan hugeicons:build
   

3. Use Pro variants:

   <flux:icon.hugeicons.home-01 variant="solid-rounded" />
   

4. Dynamic Icon Selection

@php
  $iconName = request()->routeIs('dashboard') ? 'dashboard-01' : 'home-01';
@endphp
<flux:icon.hugeicons.{{ $iconName }} />

Integration Tips

• Livewire: Pass icons as props:

  <livewire:dashboard icon="hugeicons.analytics-02" />
  

• Tailwind: Combine with Flux utilities:

  <flux:icon.hugeicons.user-01 class="size-5 text-indigo-600" />
  

• Dark Mode:

  <flux:icon.hugeicons.moon-01 class="size-6 dark:text-gray-300" />
  

Performance Patterns

• Lazy Loading: Icons are statically compiled.
• Selective Pro Builds: Generate only used Pro styles.
• Caching: Leverages Laravel’s view caching.

Gotchas and Tips

Pitfalls

1. PHP 8.2 Dropped

   • Issue: Package now requires PHP 8.3+ (removed 8.2 support).
   • Fix: Upgrade PHP or use v1.0.1 if stuck on 8.2.

2. Icon Naming Mismatches

   • Use kebab-case (e.g., home-01), not snake_case or camelCase.
   • Debug: Verify names via Hugeicons browser.

3. Pro Styles Not Found

   • Ensure:
     • Pro package is installed (e.g., @hugeicons-pro/core-solid-rounded).
     • php artisan hugeicons:build was run.
     • HUGEICONS_PRO_LICENSE_KEY is set in .env.

4. Flux Namespace

   • Must use flux:icon.hugeicons.* (not hugeicon).
   • Fix: Update Blade templates.

5. Node.js Dependencies

   • Pro icon generation requires Node.js/npm.
   • Workaround: Use free icons or pre-generate Pro icons offline.

Debugging Tips

• Check Generated Icons:

  ls resources/views/vendor/flux/components/icon/hugeicons
  

• Log Pro Build Output:

  php artisan hugeicons:build --verbose
  

• Fallback Behavior:

  <flux:icon.hugeicons.search-01 variant="solid-rounded" class="size-8" x-on:error="fallbackTo('stroke-rounded')" />
  

Configuration Quirks

1. .npmrc Placeholder

   • ${HUGEICONS_PRO_LICENSE_KEY} is safe to commit (replaced at runtime).
   • Avoid: Hardcoding keys in .npmrc.

2. Artisan Command Order

   • Run npm install before php artisan hugeicons:build.

3. Flux Version Compatibility

   • Tested with Flux UI 2. Older versions may fail.
   • Fix: Update Flux or check compatibility table.

Extension Points

1. Custom Icon Sets

   • Publish config:

     php artisan vendor:publish --provider="Abduns\HugeiconsFlux\HugeiconsFluxServiceProvider" --tag="config"
     

   • Modify config/hugeicons-flux.php.

2. Dynamic Resolution

   • Extend the icon resolver logic in app/Providers/HugeiconsFluxServiceProvider.php.

3. Testing

   • Updated to Pest v4 (no breaking changes for users).
   • Use --coverage flag for test reports:

     vendor/bin/pest --coverage