Download the PHP package livewire/blaze without Composer

🔥 Blaze

Speed up your Laravel app with optimized Blade component rendering.

Introduction

Out of the box, Blaze is a drop-in replacement for anonymous Blade components that requires no changes to your existing code.

It works by compiling your templates into optimized PHP functions instead of using the standard rendering pipeline — eliminating 91-97% of the overhead while maintaining near full feature parity with Blade.

For even greater performance, Blaze offers two additional strategies. These require extra configuration and careful consideration:

• Memoization: caching for repeated renders
• Folding: pre-rendering into static HTML

Installation

You may install Blaze via Composer:

[!TIP] If you're using Flux UI, simply install Blaze and you're ready to go — no configuration needed!

Getting started

There are two ways to enable Blaze:

A) Add the @blaze directive to individual components — great for trying it out or enabling Blaze on specific templates.

B) Optimize entire directories from your service provider — ideal for optimizing many components at once.

After enabling Blaze with either approach, clear your compiled views:

Option A: The @blaze directive

Add @blaze to the top of any anonymous component to enable Blaze for that template:

Strategies may be specified as arguments:

Option B: Optimize directories

Call Blaze::optimize() in your AppServiceProvider to enable Blaze for entire directories at once:

We recommend starting with specific directories, as your app may rely on features Blaze doesn't support. Gradually expand coverage and verify compatibility with known limitations.

To exclude a subdirectory, use compile: false.

You may also enable different optimization strategies per folder.

Component-level @blaze directives override directory-level settings.

Limitations

Blaze supports all essential features and produces HTML output identical to Blade. While the focus is on maximizing performance with full compatibility, there are some limitations to be aware of:

• Class-based components are not supported
• The $component variable is not available
• View composers / creators / lifecycle events do not fire

• Auto-injecting View::share() variables is not supported

  Access shared data manually using $__env->shared('key')

• Cross boundary @aware between Blade and Blaze

  Both parent and child must use Blaze for values to propagate

• Rendering Blaze components using view() will not work

  Blaze components can only be rendered using the component tag

Optimization Strategies

By default, Blaze uses the Function Compiler. It works for virtually all components and provides significant performance improvements — sufficient for most use cases.

For even greater gains, you may consider the advanced strategies below. These require additional thought and care.

Function Compiler

This is the default behavior. It's a reliable optimization that requires no changes and can be safely applied to nearly all templates without concerns about stale data or dynamic content.

Rendering 25,000 anonymous components in a loop:

These numbers reflect rendering pipeline overhead. If your templates perform expensive operations internally, that work will still affect performance.

How it works

When you enable Blaze, your templates are compiled into optimized PHP functions that skip the standard rendering pipeline while maintaining compatibility with Blade syntax.

Compiles to:

When you include the component, Blaze calls this function directly.

Becomes:

Runtime Memoization

This strategy is ideal for icons, avatars, and other elements that frequently appear with the same props. When a memoized component appears multiple times on a page, it renders only once.

[!IMPORTANT] Memoization only works on components without slots.

How it works

The output is cached based on the component name and props passed to it.

When you include the component, Blaze wraps it in a cache check and only renders it the first time it's used with those props.

Becomes:

Compile-Time Folding

Compile-time folding is Blaze's most aggressive optimization. The component ceases to exist at runtime — no function call, no variable resolution, no overhead whatsoever. Just the HTML.

Rendering time remains constant regardless of component count:

[!CAUTION] Folding requires careful consideration. Used incorrectly, it can cause subtle bugs that are difficult to diagnose. Make sure you fully understand how it works before enabling this strategy.

How It Works

Blaze pre-renders components during compilation, embedding the HTML directly into your template. This eliminates all runtime overhead, enabling exceptional performance gains. However, these gains come at a cost — folding requires a thorough understanding of its mechanics and careful consideration.

The following sections explore how folding works so you can use it safely.

Overview

The most important thing to understand is that folding produces static HTML. All internal logic, conditions, and dynamic content are baked in at compile time. This can create subtle bugs where a component works correctly in some places but breaks in others.

Blaze tries to avoid folding when it's likely to cause problems, but it cannot detect all cases. You'll need to analyze each component individually and configure when folding should be aborted.

Global state

Components that use global state should never be folded. This includes anything not passed in from the outside — data accessed via helper functions, facades, or Blade directives. Using any of these patterns inside the component will produce incorrect results when folded.

[!WARNING] Components that use global state must not be marked with fold: true. Blaze attempts to detect global state usage and will throw an exception when it does, but it cannot catch everything.

This applies to internal logic. Passing global state into the component via attributes or slots can be fine — however, there are exceptions. We'll explore these in the following sections.

Static attributes

Let's explore the folding process with a simple example where everything works smoothly.

Consider a button component that dynamically resolves Tailwind classes based on the color prop.

When you include it with a static prop:

Blaze renders the component and replaces it with static HTML during compilation:

The component only needed to be rendered once — subsequent requests simply serve the static HTML. All dynamic parts have been folded away, and the color="red" prop has been transformed into a static class name.

This worked because all props were static. They never change, so Blaze can safely remove all dynamic parts while still producing the correct output.

Dynamic pass-through attributes

The next example illustrates a scenario with dynamic attributes where folding still works correctly.

Even though Blaze doesn't have access to runtime data, it works around this by replacing dynamic attributes with placeholders and substituting the original expressions back into the final output.

Let's assign a random id to the button:

During compilation, Blaze identifies dynamic attributes and stores their values:

Next, it pre-renders the component using the placeholder:

Which results in:

Finally, Blaze substitutes the original expression back into the HTML:

This worked because id is a pass-through attribute — it's output directly without transformation or use in internal logic.

Dynamic non-pass-through attributes

The next example illustrates a scenario with dynamic attributes where folding breaks.

Blaze automatically aborts folding when a component receives a dynamic attribute that is also defined in @props. It falls back to function compilation and the performance benefits of folding are not realized.

Blaze assumes that attributes defined in @props are likely used in internal logic and therefore should not be folded. This defensive behavior avoids most common errors. However, there are cases where this is too restrictive, which we'll explore in Selective folding.

To understand why folding breaks, let's see what would happen if it weren't aborted.

Pass a dynamic attribute to the color prop:

Blaze creates the mapping table and pre-renders with a placeholder:

Here's where the problem occurs. Inside the component, $color now evaluates to the literal string "ATTR_PLACEHOLDER_1":

The match lookup fails and falls back to the default — the button is always gray:

Slots

Slots are handled similarly to attributes — replaced with placeholders during pre-rendering and restored afterwards. Unlike attributes, slots are always considered pass-through and will never abort folding unless marked as unsafe (see Selective folding).

During compilation, Blaze stores slot values:

Blaze pre-renders with the placeholder:

Which results in:

Finally, Blaze substitutes the original expression back into the HTML:

Selective folding

By default, Blaze errs on the side of caution and aborts folding when dynamic values are detected in attributes defined in @props. This prevents many common mistakes but can be overly restrictive. Similarly, slots are always considered pass-through, which may not suit every case.

You may fine-tune this behavior using the safe and unsafe parameters of the @blaze directive.

Using safe

Use safe to mark props that are pass-through — they're not transformed or used in internal logic. This allows folding to proceed even when those props are dynamic.

The component now folds successfully, producing:

Using unsafe for slots

Use unsafe to mark slots that are not pass-through — they're transformed or used in internal logic. This forces folding to abort.

This also works with named slots:

The component now correctly aborts folding whenever it receives a slot.

[!IMPORTANT] Blaze does not inspect slot content to determine if it's dynamic or static. When a slot is marked as unsafe, folding is always aborted regardless of the actual content. Self-closing components will still fold successfully.

Using unsafe for attributes

You may also mark attributes that are not defined in @props as unsafe.

This prevents folding errors when non-pass-through attributes are resolved dynamically via $attributes:

You may also mark the entire attribute bag as unsafe:

Any dynamic attributes will now cause folding to abort.

The Unblaze Directive

When a component is mostly foldable but contains a dynamic section, use @unblaze to exclude that section:

Variables from the component scope must be passed explicitly using the scope parameter.

Debug Mode

Blaze includes a powerful debug mode to help you measure rendering performance, compare Blaze against standard Blade and find performance bottlenecks.

Enabling debug mode

Enable debug mode from your service provider:

Or set the environment variable in your .env file:

After enabling, clear your compiled views:

The overlay

When debug mode is active, a small overlay appears on every page showing the rendering time for the current request.

Comparing Blaze vs Blade

You can record baseline times with Blade and compare them against Blaze:

1. Disable Blaze temporarily by setting BLAZE_ENABLED=false in your .env file
2. Run php artisan view:clear to recompile views without Blaze
3. Visit the page — the debug bar records the Blade rendering time
4. Re-enable Blaze by removing the environment variable
5. Run php artisan view:clear again to recompile with Blaze
6. Visit the same page — the debug bar shows the Blaze time alongside the Blade baseline with the difference

Refresh the page a few times in each mode to get the best result — the first load may include compilation overhead that skews the numbers. Blaze will display the difference in savings between the two rendering pipelines.

The profiler

The debug overlay includes an Open Profiler button that opens a separate window displaying a flame chart trace for the last visited URL.

The profiler workflow:

1. Open the profiler window (it can stay open)
2. Navigate to the page you want to profile
3. Refresh the profiler window — it loads the trace for that page

The trace shows every component rendered during the request, its duration, nesting depth, and which strategy was used (compiled, folded, memoized, or blade).

[!NOTE] The profiler stores trace data in your application's default cache store. If the cache driver is set CACHE_STORE=array or the cache is otherwise unreachable, the profiler will not work.

Reference

Directive Parameters

Accepted values for safe and unsafe:

Directory Configuration

Blaze Methods

Environment Variables

License

The MIT License (MIT). Please see License File for more information.