Blaze

When using fold: true, you must tell Blaze how to handle dynamic values for props, slots, and attributes to prevent breaking the component.

safe parameter

Use safe for @props that are passed through to the output without internal logic/transformation. This allows folding to proceed even when the caller passes a dynamic expression.

unsafe parameter

Use unsafe for values that are used in internal logic (e.g., match, if, switch) or if the component inspects slot content or the attribute bag. When a value marked unsafe receives a dynamic input, folding is aborted for that instance.

Target Values

{{-- Marking a prop as safe for pass-through --}}
@blaze(fold: true, safe: ['level'])

{{-- Marking a slot as unsafe because logic depends on it --}}
@blaze(fold: true, unsafe: ['slot'])

{{-- Marking the attribute bag as unsafe --}}
@blaze(fold: true, unsafe: ['attributes'])

To enable Blaze for many components at once, call Blaze::optimize() within your AppServiceProvider's boot method. This allows you to target specific directories and apply different optimization strategies per folder.

Key features:

• Use ->in(path) to target a directory.
• Use compile: false to exclude a subdirectory.
• Pass optimization parameters like memo: true or fold: true to the in() method.
• Component-level @blaze directives will override these directory-level settings.

Note: After enabling Blaze, you must clear your compiled views using php artisan view:clear.

use Livewire\
Blaze\Blaze;

public function boot(): void
{
    // Optimize specific directories
    Blaze::optimize()->in(resource_path('views/components'));

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

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

Compile-time folding pre-renders components during Blade compilation, embedding static HTML directly into the parent template. This eliminates runtime overhead but can cause bugs if the component relies on dynamic global state.

Do NOT fold a component if it accesses any of the following:

• Database: DB::, ::where(), ::find(), ::get(), etc.
• Auth: auth(), @auth, @guest, Auth::, or $user from auth.
• Session: session(), Session::.
• Request: request(), Request::, $request.
• Validation: $errors, @error.
• Time: now(), Carbon::, today(), time().
• CSRF: @csrf, csrf_token().
• URL state: url()->current(), request()->path(), etc.
• Config/Env: config(), env() (if values change between requests).
• Cache: Cache::, cache().
• App state: app(), resolve(), App::.

Exception: If only a small section requires global state, use @unblaze with a scope to exclude that specific part from the folding process.

@blaze(fold: true)

@props(['name', 'label'])

<div class="container">
    <label>{{ $label }}</label>
    <input name="{{ $name }}">

    @unblaze(scope: ['name' => $name])
        @if($errors->has($scope['name']))
            {{ $errors->first($scope['name']) }}
        @endif
    @endunblaze
</div>

Props Analysis

• Static props: (e.g., color="red") are safe to fold.
• Dynamic pass-through props: (e.g., :level="$isFeatured ? 1 : 2") are safe ONLY IF marked with safe: ['prop_name'].
• Dynamic non-pass-through props: (e.g., :color="$deleting ? 'red' : 'blue'" where color is used in a match statement) CANNOT be folded.

Slot Analysis

• Default slot: Generally safe as they are treated as pass-through.
• Slots used in logic: If you use $slot->hasActualContent() or $slot->isEmpty(), you MUST mark the slot as unsafe: ['slot'].
• Named slots in logic: If a named slot (e.g., footer) is inspected via logic, mark it unsafe: ['footer'].

Attribute Bag Analysis

If the component reads attributes via $attributes->get() and uses them in logic (rather than just merging them), mark attributes or the specific attribute name as unsafe.