Blaze Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require livewire/blaze:^1.0
   

2. Enable for a single component (quick test):

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

   Clear compiled views:

   php artisan view:clear
   

3. Verify performance by testing rendering speed in your application (e.g., loop rendering 25k components).

First Use Case

Replace a slow-rendering anonymous component (e.g., a modal or button) with @blaze and measure the difference. Example:

@blaze
<div class="modal">
    {{ $slot }}
</div>

Implementation Patterns

Core Workflow

1. Start Small: Use @blaze on high-impact components (e.g., repeated UI elements like buttons, cards, or modals).
2. Directory Optimization: Gradually enable Blaze for entire directories via AppServiceProvider:

   Blaze::optimize()->in(resource_path('views/components'));
   

3. Override Strategies: Use @blaze(memo: true) or @blaze(fold: true) for specific components.

Integration Tips

• Livewire Compatibility: Blaze works seamlessly with Livewire components (no changes needed).
• Flux UI: Automatically enabled if using Flux UI.
• Conditional Rendering: Use @if/@unless inside Blaze components (supported, but avoid global state).
• Dynamic Props: Blaze handles dynamic props (e.g., :color="$dynamicValue") via placeholders.

Advanced Patterns

1. Memoization for Icons:

   @blaze(memo: true)
   <x-dynamic-component :component="'icon-' . $name" />
   

   Cache repeated renders (e.g., icons, avatars).

2. Folding for Static Content:

   @blaze(fold: true)
   <div class="static-content">{{ $staticText }}</div>
   

   Pre-render static HTML (use cautiously; see Gotchas).

3. Hybrid Approach:

   Blaze::optimize()
       ->in(resource_path('views/components/icons'), memo: true)
       ->in(resource_path('views/components/cards'), fold: true);
   

   Combine strategies per directory.

Gotchas and Tips

Pitfalls

1. Global State:

   • Problem: Folding breaks if components use global state (e.g., auth()->user(), now()).
   • Fix: Avoid fold: true for components with:
     • Database queries (User::find()).
     • Facades (Cache::get()).
     • Blade directives (@auth, @csrf).
   • Workaround: Pass state via props or use memo: true instead.

2. Dynamic Props in @props:

   • Problem: Folding aborts if a dynamic prop matches @props (e.g., :color="$dynamicColor").
   • Fix: Use fold: true only for static props or refactor to avoid conflicts.

3. Slots with Dynamic Content:

   • Problem: Slots with dynamic content (e.g., {{ $user->name }}) may render incorrectly if folded.
   • Fix: Use memo: true or avoid folding for such slots.

4. Class-Based Components:

   • Problem: Blaze does not support class-based components (e.g., <x-Button /> with a PHP class).
   • Fix: Use anonymous components only.

5. View Composers/Creators:

   • Problem: Blaze skips view composers/creators.
   • Fix: Manually inject shared data via $__env->shared('key').

Debugging Tips

• Check Compilation: Run php artisan view:clear after changes.
• Verify Output: Compare Blaze-rendered HTML with Blade’s output (should match).
• Enable Debugging:

  Blaze::debug(); // Logs compilation warnings/errors
  

• Test Incrementally: Enable Blaze for one component/directory at a time.

Extension Points

1. Custom Compilers:

   • Extend BlazeCompiler to support custom syntax or logic.
   • Example: Add a @blaze(optimize: 'custom') directive.

2. Memoization Keys:

   • Override memoization key generation for complex props:

     Blaze::memoizeUsing(function ($component, $props) {
         return md5($component . serialize($props));
     });
     

3. Folding Exclusions:

   • Use compile: false to exclude directories:

     Blaze::optimize()
         ->in(resource_path('views/components/legacy'), compile: false);
     

Performance Quirks

• Memoization Overhead: Memoized components add minimal runtime checks (~1ms per component).
• Folding Trade-offs:
  • Pros: Zero runtime overhead for static content.
  • Cons: Cannot handle dynamic logic (e.g., @if($dynamicVar)).
• Benchmark: Use blade:profile to identify slow components before optimizing:

  php artisan blade:profile