Blaze Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require livewire/blaze:^1.0
   

   No additional dependencies or complex setup required.

2. Enable for a Single Component Add the @blaze directive to any Blade template:

   @blaze
   <div>
       {{ $slot }}
   </div>
   

   This replaces the standard Blade rendering pipeline for this component.

3. First Use Case Optimize a frequently rendered anonymous component (e.g., a dropdown, modal, or card) by wrapping it in @blaze. Test performance with:

   php artisan blaze:benchmark
   

   Compare before/after render times in your browser’s dev tools.

Implementation Patterns

Core Workflow

1. Selective Optimization Use @blaze on components with high render frequency (e.g., tooltips, loading spinners, or repeated UI elements). Avoid over-optimizing rarely used templates.

2. Directory-Level Optimization In your AppServiceProvider’s boot() method, register Blaze for entire directories:

   use Livewire\Blaze\Facades\Blaze;
   
   public function boot(): void
   {
       Blaze::optimizeDirectory(resource_path('views/components'));
   }
   

   This compiles all Blade files in the directory into optimized PHP functions.

3. Integration with Livewire Blaze works seamlessly with Livewire components. No changes needed—just wrap your Blade templates:

   @blaze
   <x-livewire-example />
   

4. Conditional Rendering Combine with Blade’s @if directives for dynamic optimization:

   @if(request()->wantsJson())
       @blaze
       <div>{{ $content }}</div>
   @else
       <div>{{ $content }}</div>
   @endif
   

Advanced Patterns

• Memoization for Static Data Cache repeated renders of components with static data:

  @blaze(memoize)
  <div>{{ $staticData }}</div>
  

  Configure memoization keys in config/blaze.php:

  'memoization' => [
      'enabled' => true,
      'cache_store' => 'file',
  ],
  

• Folding for Static HTML Pre-render components into static HTML (requires php artisan blaze:fold):

  @blaze(fold)
  <div>Static content</div>
  

  Useful for hero sections, footers, or documentation pages.

• Hybrid Approach Use @blaze for dynamic components and @once for static fallbacks:

  @once
      @blaze
      <div>{{ $dynamicContent ?? 'Fallback' }}</div>
  @endonce
  

Gotchas and Tips

Pitfalls

1. Not All Blade Features Supported

   • Unsupported: @stack, @push, @prepend, or dynamic component registration (@component('dynamic-name')).
   • Workaround: Use parent templates or inline Blade for unsupported features.
   • Debugging: Check storage/logs/blaze.log for unsupported directive warnings.

2. Memoization Cache Invalidation

   • Memoized components cache based on their compiled hash. Changes to the template or its dependencies (e.g., CSS/JS) won’t invalidate the cache automatically.
   • Fix: Clear the cache manually:

     php artisan cache:clear
     php artisan blaze:clear
     

3. Folding Limitations

   • Folded components cannot include dynamic data (e.g., {{ $user->name }}).
   • Tip: Use folded components only for truly static content or combine with @blaze(memoize) for semi-static cases.

4. Livewire Component Conflicts

   • Blaze optimizes the Blade template, not the Livewire component logic. Ensure your component’s render() method doesn’t rely on Blade-specific behavior (e.g., @stack pushes).
   • Debugging: Temporarily disable Blaze (php artisan blaze:disable) to isolate issues.

5. Development vs. Production

   • Blaze is automatically disabled in debug mode (APP_DEBUG=true). Test optimizations in a staging environment or locally with APP_DEBUG=false.

Tips

1. Benchmark Strategically Use php artisan blaze:benchmark to measure improvements. Focus on components with:

   • High render counts (e.g., modals, dropdowns).
   • Complex nested Blade logic.
   • External API calls (Blaze won’t optimize these; use memoization instead).

2. Exclude Directories Opt out of directory optimization in config/blaze.php:

   'directories' => [
       resource_path('views/components') => true,
       resource_path('views/emails') => false, // Exclude emails
   ],
   

3. Custom Compilation Logic Extend Blaze’s compiler by publishing and modifying the config:

   php artisan vendor:publish --tag=blaze-config
   

   Override BlazeCompiler in app/Providers/BlazeServiceProvider.php:

   public function register(): void
   {
       $this->app->singleton(BlazeCompiler::class, function () {
           return new CustomBlazeCompiler();
       });
   }
   

4. Monitor Performance Track Blaze’s impact with Laravel’s query log or custom metrics:

   // In AppServiceProvider
   Blaze::optimized(function (string $component, float $duration) {
       info("Blaze optimized {$component} in {$duration}ms");
   });
   

5. Fallback for Unsupported Cases Use a helper to conditionally enable Blaze:

   if (app()->environment('production') && !Blaze::isSupported($content)) {
       return $content; // Fallback to standard Blade
   }
   return Blaze::render($content);