diff --git a/README.md b/README.md index a7e686fe..8348110a 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,7 @@ Blaze will automatically optimize it during compilation, pre-rendering the stati ## Table of contents - [When to use @blaze](#when-to-use-blaze) +- [Making impure components Blaze-eligible with @unblaze](#making-impure-components-blaze-eligible-with-unblaze) - [Performance expectations](#performance-expectations) - [Debugging](#debugging) - [AI assistant integration](#ai-assistant-integration) @@ -284,6 +285,141 @@ When a component can't be folded due to dynamic content, Blaze automatically fal - **Test thoroughly**: After adding `@blaze`, verify the component still works correctly across different requests - **Blaze is forgiving**: If a component can't be optimized, Blaze will automatically fall back to normal rendering +## Making impure components Blaze-eligible with @unblaze + +Sometimes you have a component that's *mostly* static, but contains a small dynamic section that would normally prevent it from being folded (like `$errors`, `request()`, or `session()`). The `@unblaze` directive lets you "punch a hole" in an otherwise static component, keeping the static parts optimized while allowing specific sections to remain dynamic. + +### The problem + +Imagine a form input component that's perfect for `@blaze` - except it needs to show validation errors: + +```blade +{{-- ❌ Can't use @blaze - $errors prevents optimization --}} + +
+ + + + @if($errors->has($name)) + {{ $errors->first($name) }} + @endif +
+``` + +Without `@unblaze`, you have to choose: either skip `@blaze` entirely (losing all optimization), or remove the error handling (losing functionality). + +### The solution: @unblaze + +The `@unblaze` directive creates a dynamic section within a folded component: + +```blade +{{-- ✅ Now we can use @blaze! --}} + +@blaze + +@props(['name', 'label']) + +
+ + + + @unblaze + @if($errors->has($name)) + {{ $errors->first($name) }} + @endif + @endunblaze +
+``` + +**What happens:** +- The `
`, `