> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Blaze 패키지 소개

> Livewire 공식 Blaze를 사용하여 Blade 컴포넌트 렌더링을 고속화하는 방법을 설명합니다. compile / memo / fold의 선택 기준, 도입 방법, 제한 사항, 내부 동작 방식까지 정리합니다.

<Info>
  이 글은 [livewire/blaze](https://github.com/livewire/blaze)의 README를 1차 정보로 삼아 정리한 것입니다. 현재 시점에서 laravel.com 측에는 Blaze 전용 문서가 없습니다.
</Info>

## Blaze란 무엇인가

[Blaze](https://github.com/livewire/blaze)는 Livewire 공식이 공개한 Blade 컴포넌트 고속화 패키지입니다. 대상은 Livewire 컴포넌트뿐만 아니라 일반적인 익명 Blade 컴포넌트도 포함됩니다.

README에서는 익명 컴포넌트 25,000회 렌더링 벤치마크로 **500ms → 13ms** (약 **97.4% 감소**)가 제시되어 있습니다. 시나리오별로도 91\~97%의 감소가 보고되고 있습니다.

## 세 가지 최적화 전략

Blaze는 `compile`(기본값), `memo`, `fold`의 3가지 전략을 제공합니다.

```mermaid theme={null}
flowchart LR
    A["컴포넌트 호출"] --> B["compile<br>함수 컴파일"]
    A --> C["memo<br>동일 props 메모이제이션"]
    A --> D["fold<br>컴파일 타임 HTML화"]
    B --> E["넓은 호환성과 큰 개선"]
    C --> F["반복 렌더링에 강함"]
    D --> G["최대 성능이나 주의 필요"]
```

### 어느 것을 선택할 것인가

| 전략        | 언제 선택할까                          | 장점                       | 주의점                          |
| --------- | -------------------------------- | ------------------------ | ---------------------------- |
| `compile` | 가장 먼저 선택하는 표준 전략                 | 호환성이 높고, 설정 없이 쉽게 고속화 가능 | 제한 사항은 공통이므로 확인 필요           |
| `memo`    | 동일한 props로 여러 번 렌더링하는 아이콘 · 배지 등 | 초기 이후 재렌더링 비용을 낮출 수 있음   | slot을 가진 컴포넌트에서는 사용 불가       |
| `fold`    | 정적으로 확정 가능한 UI에서 최대 성능을 노릴 때     | 런타임 오버헤드를 거의 제거 가능       | 전역 상태나 동적 값의 취급을 잘못하면 불일치 발생 |

판단이 어려울 경우 **`compile`로 시작**하여, 병목이 특정된 곳에만 `memo` / `fold`를 적용하는 방식이 안전합니다.

## 설치 및 활성화

```bash theme={null}
composer require livewire/blaze:^1.0
```

활성화는 두 가지 방법이 있습니다.

### 1) `@blaze`를 개별 컴포넌트에 붙이기

```blade theme={null}
@blaze

<button {{ $attributes }}>
    {{ $slot }}
</button>
```

필요에 따라 전략을 전환합니다.

```blade theme={null}
@blaze(memo: true)
@blaze(fold: true)
```

### 2) `Blaze::optimize()`로 디렉터리 단위로 활성화

```php theme={null}
use Livewire\Blaze\Blaze;

public function boot(): void
{
    Blaze::optimize()
        ->in(resource_path('views/components'));
}
```

활성화 후에는 컴파일된 뷰를 클리어합니다.

```bash theme={null}
php artisan view:clear
```

<Tip>
  `@blaze`는 "우선 시험 삼아 써보기" 용도, `Blaze::optimize()`는 "운영에서 넓게 적용하기" 용도에 적합합니다. README에서도 우선 한정된 디렉터리부터 단계적으로 적용할 것을 권장하고 있습니다.
</Tip>

## 제한 사항

README에 명시된 제한 사항입니다.

* 클래스 기반 컴포넌트는 비지원
* `$component` 변수 사용 불가
* View composers / creators / lifecycle events는 발화하지 않음
* `View::share()` 변수의 자동 인젝트는 비지원 (필요한 경우 `$__env->shared('key')`를 명시적으로 사용)
* Blade와 Blaze를 넘나드는 `@aware`는 제한 있음 (부모와 자식 모두 Blaze 측에서 사용해야 함)
* `view()`로 Blaze 컴포넌트를 직접 렌더링할 수 없음 (컴포넌트 태그 경유만 가능)

## Flux UI와의 궁합

Blaze README에서는 [Flux UI](https://fluxui.dev/docs/installation)를 사용하고 있는 경우 **Blaze를 설치하는 것만으로 추가 설정 없이 이용 가능**하다고 안내되어 있습니다.

## 동작 방식 개요

일반적인 Blade는 컴포넌트 해결이나 속성 처리를 포함한 렌더링 파이프라인을 매번 통과합니다. Blaze의 `compile`은 이를 최적화된 PHP 함수로 컴파일하여 직접 호출함으로써 파이프라인의 오버헤드를 크게 줄입니다.

README의 설명에 따르면, 개념적으로는 다음과 같은 차이가 있습니다.

* 일반: Blade의 표준 렌더링 처리를 매번 실행
* Blaze `compile`: 컴파일된 함수를 직접 호출
* Blaze `fold`: 컴파일 타임에 HTML을 삽입하여, 런타임 계산을 더욱 줄임

`fold`는 가장 빠르지만, 정적화의 전제를 깨는 요소(인증 상태, 요청 의존 값, 세션 의존 값, 시간 의존 값 등)가 있으면 버그의 원인이 됩니다. 부하가 높은 곳만을 대상으로, 동작을 확인하면서 단계적으로 적용하시기 바랍니다.


## Related topics

- [Laravel Wayfinder 소개](/ko/blog/wayfinder-introduction.md)
- [Laravel Agent Detector — AI 에이전트 감지 패키지](/ko/blog/agent-detector-introduction.md)
- [Laravel Telescope 실전 테크닉](/ko/blog/telescope-introduction.md)
- [Inertia.js로 SPA 구축하기](/ko/blog/inertia-introduction.md)
- [Laravel Pennant 실전 유스케이스](/ko/blog/laravel-pennant.md)