Blade Coolicons Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require codeat3/blade-coolicons
   

2. Cache Icons (Critical for production):

   php artisan icons:cache
   

   Add this to your deployment pipeline (e.g., deploy.php or CI/CD script).

3. First Usage: Use any Coolicons icon directly in Blade:

   <x-coolicon-bulb class="w-5 h-5 text-blue-500"/>
   

   Verify the icon renders correctly by inspecting the compiled SVG in the browser.

Where to Look First

• Coolicons Preview – Browse available icons and their names (e.g., bulb, heart).
• Blade Icons Docs – Understand advanced features like caching, theming, or default attributes.
• Published Config (config/blade-coolicons.php) – Check if default classes/attributes need customization.

First Use Case

Replace a legacy icon system (e.g., Font Awesome or custom SVGs) in a high-traffic component like a dashboard header or navigation bar. Example migration:

<!-- Before (Font Awesome) -->
<i class="fas fa-bell"></i>

<!-- After (Blade Coolicons) -->
<x-coolicon-bell class="w-6 h-6"/>

Implementation Patterns

Usage Patterns

1. Basic Icon Usage

• Self-closing components for simplicity:

  <x-coolicon-home/>
  

• Dynamic classes (Tailwind/utility-first):

  <x-coolicon-settings class="w-4 h-4 text-gray-400 hover:text-gray-600"/>
  

2. Conditional Icons

• Use Blade directives to toggle icons based on logic:

  @auth
      <x-coolicon-user class="w-5 h-5"/>
  @else
      <x-coolicon-login class="w-5 h-5"/>
  @endauth
  

3. Icon with Inline Styles

• Override styles dynamically (e.g., for dark mode):

  <x-coolicon-moon style="color: {{ request()->wantsDarkMode() ? '#9ca3af' : '#1f2937' }}"/>
  

4. Raw SVG Assets

• Publish SVGs once and reuse them:

  php artisan vendor:publish --tag=blade-coolicons --force
  

  <img src="{{ asset('vendor/blade-coolicons/bulb.svg') }}" alt="Bulb" width="24" height="24"/>
  

• Use case: For non-Blade contexts (e.g., email templates, PDF generation with DomPDF).

5. Icon Sets in Loops

• Render dynamic lists (e.g., feature flags or menu items):

  @foreach($menuItems as $item)
      <x-coolicon-{{ $item->icon }} class="w-5 h-5 mr-2"/>
      {{ $item->name }}
  @endforeach
  

Workflows

Development Workflow

1. Local Testing:
   • Skip caching in development (config/blade-coolicons.php set cache to false).
   • Use php artisan icons:clear to reset cached icons during development.
2. Icon Discovery:
   • Search for icons via Coolicons.cool and test them in Blade:

     @foreach(['home', 'settings', 'logout'] as $icon)
         <x-coolicon-{{ $icon }}/>
     @endforeach
     

Production Workflow

1. Cache Icons:

   php artisan icons:cache
   

   • Add to post-deploy hook (e.g., Forge/Deployer):

     task('deploy:icons', function () {
         run('php artisan icons:cache');
     })->desc('Cache Blade Coolicons icons');
     

2. Monitor Performance:
   • Use Chrome DevTools to verify SVG render time (should be <1ms after caching).

Integration Tips

Tailwind CSS

• Leverage Tailwind’s JIT mode for dynamic icon sizing/colors:

  <x-coolicon-star class="w-{{ $rating }} h-{{ $rating }} text-yellow-400"/>
  

• Pro Tip: Create a custom Tailwind plugin to auto-apply icon classes:

  // tailwind.config.js
  module.exports = {
      plugins: [
          function({ addComponents }) {
              addComponents({
                  '.icon-default': {
                      'width': '1em',
                      'height': '1em',
                      'color': 'currentColor'
                  }
              });
          }
      ]
  };
  

  <x-coolicon-home class="icon-default text-gray-500"/>
  

Livewire/Alpine.js

• Use icons in interactive components:

  <div x-data="{ open: false }">
      <button @click="open = !open">
          <x-coolicon-chevron-down class="w-4 h-4 transition-transform" :class="{ 'rotate-180': open }"/>
      </button>
  </div>
  

Dark Mode

• Sync icon colors with dark mode using Laravel’s request()->wantsDarkMode():

  <x-coolicon-moon class="text-gray-500 dark:text-gray-400"/>
  

  Or dynamically:

  <x-coolicon-moon :class="request()->wantsDarkMode() ? 'text-gray-400' : 'text-gray-500'"/>
  

Custom Icons

• Option 1: Fork the package and add SVGs to resources/svg/ (requires rebuilding components).
• Option 2: Use Blade Icons’ custom icon support:

  php artisan icons:make custom-icon --name=my-custom-icon
  

  Then reference it in Blade:

  <x-coolicon-my-custom-icon/>
  

Gotchas and Tips

Pitfalls

1. Forgetting to Cache Icons in Production

   • Symptom: Icons render as broken SVGs or with slow load times.
   • Fix: Always run php artisan icons:cache post-deploy. Add it to your deployment script.
   • Debug: Check storage/framework/cache/data/blade-icons/ for cached files.

2. Icon Names Mismatch

   • Symptom: <x-coolicon-nonexistent/> renders nothing or throws an error.
   • Fix: Verify icon names against Coolicons.cool. Use lowercase, kebab-case (e.g., cool-icon, not CoolIcon).
   • Debug: List all available icons with:

     php artisan icons:list
     

3. Caching Issues After Icon Updates

   • Symptom: New icons don’t appear after package updates.
   • Fix: Clear and regenerate cache:

     php artisan icons:clear
     php artisan icons:cache
     

4. SVG Attribute Conflicts

   • Symptom: Icons lose styling or hover effects due to conflicting stroke attributes.
   • Fix: Override inline styles or update the package’s SVG templates (see Blade Icons issue #123).

5. Non-Blade Contexts

   • Symptom: Raw SVGs don’t render when published.
   • Fix: Ensure the public/vendor/blade-coolicons/ directory exists and permissions are correct (chmod -R 755).

Debugging

Config Quirks

1. Default Attributes
   • Configure global defaults in config/blade-coolicons.php:

     'defaults' => [
         'class' => 'w