diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 0c38da22..951572dd 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -16,7 +16,7 @@ A clear and concise description of what the bug is. ``` **Expected behavior** -What you expected to happen when using `@pure`. +What you expected to happen when using `@blaze`. **Actual behavior** What actually happened instead. @@ -27,4 +27,4 @@ What actually happened instead. - Blaze version: [e.g. 1.0.0] **Additional context** -Add any other context about the problem here (error messages, stack traces, etc.) \ No newline at end of file +Add any other context about the problem here (error messages, stack traces, etc.) diff --git a/AGENTS.md b/AGENTS.md index 7d1c4e57..63f475e9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,36 +6,36 @@ This document provides guidance for AI assistants helping users work with Larave Laravel Blaze is a performance optimization package that pre-renders static portions of Blade components at compile-time, dramatically reducing runtime overhead. It works by: -1. Identifying components marked with the `@pure` directive in their source +1. Identifying components marked with the `@blaze` directive in their source 2. Analyzing component source for runtime dependencies 3. Pre-rendering eligible components during Blade compilation 4. Falling back to normal rendering for unsafe components ## Core Concepts -### The @pure Directive +### The @blaze Directive -The `@pure` directive tells Blaze that a component has no runtime dependencies and can be safely optimized. It must be placed at the top of a component file: +The `@blaze` directive tells Blaze that a component has no runtime dependencies and can be safely optimized. It must be placed at the top of a component file: ```blade -@pure +@blaze @props(['title'])

{{ $title }}

``` -The `@pure` directive supports optional parameters to control different optimization strategies: +The `@blaze` directive supports optional parameters to control different optimization strategies: ```blade {{-- All optimizations enabled (default) --}} -@pure +@blaze {{-- Explicitly enable all optimizations --}} -@pure(fold: true, memo: true, aware: true) +@blaze(fold: true, memo: true, aware: true) {{-- Disable specific optimizations --}} -@pure(fold: false, memo: true, aware: false) +@blaze(fold: false, memo: true, aware: false) ``` **Parameters:** @@ -45,7 +45,7 @@ The `@pure` directive supports optional parameters to control different optimiza ### Code Folding Process -When a `@pure` component is encountered, Blaze: +When a `@blaze` component is encountered, Blaze: 1. Replaces dynamic content being passed in via attributes or slots with placeholders 2. Renders the component with placeholders 3. Validates that placeholders are preserved @@ -58,7 +58,7 @@ When a component can't be folded (due to dynamic content), Blaze automatically f ## Helping Users Analyze Components -When a user asks about adding `@pure` to a component or wants you to analyze their components, follow this process: +When a user asks about adding `@blaze` to a component or wants you to analyze their components, follow this process: ### 1. Read and Analyze the Component @@ -67,9 +67,9 @@ First, examine the component source code for: - Dynamic content that changes per request - Dependencies on global state or context -### 2. Safe Patterns for @pure +### 2. Safe Patterns for @blaze -Components are safe for `@pure` when they only: +Components are safe for `@blaze` when they only: - Accept props and render them consistently - Perform simple data formatting (dates, strings, etc.) - Render slots without modification @@ -77,27 +77,27 @@ Components are safe for `@pure` when they only: Examples: ```blade {{-- UI components --}} -@pure +@blaze
{{ $slot }}
{{-- Prop-based styling --}} -@pure +@blaze @props(['variant' => 'primary']) {{-- Simple formatting --}} -@pure +@blaze @props(['price']) ${{ number_format($price, 2) }} {{-- Components using @aware --}} -@pure +@blaze @aware(['theme']) @props(['theme' => 'light'])
{{ $slot }}
``` -### 3. Unsafe Patterns (Never @pure) +### 3. Unsafe Patterns (Never @blaze) **Authentication & Authorization:** - `@auth`, `@guest`, `@can`, `@cannot` @@ -134,89 +134,89 @@ Examples: - Components that display pagination controls - Data tables with pagination -**Nested Non-Pure Components:** +**Nested Non-Foldable Components:** - Components that contain other components which use runtime data -- Parent components can't be `@pure` if any child component is dynamic -- Watch for `` tags inside the component that might be non-pure +- Parent components can't be `@blaze` if any child component is dynamic +- Watch for `` tags inside the component that might be non-foldable ### 4. Analysis Process When analyzing a component: 1. **Scan for unsafe patterns** using the lists above -2. **Check for child components** - look for any `` tags and verify they are also pure +2. **Check for child components** - look for any `` tags and verify they are also foldable 3. **Check for indirect dependencies** - props that might contain dynamic data (like paginator objects) 4. **Consider context** - how the component is typically used 5. **Test edge cases** - what happens with different prop values #### Special Case: Nested Components -When a component directly renders other Blade components in its template (not via slots), verify those are also pure: +When a component directly renders other Blade components in its template (not via slots), verify those are also foldable: ```blade {{-- Parent component --}} -@pure +@blaze
- + {{ $slot }} - - + +
``` **Key distinction**: -- Components **hardcoded in the template** must be pure for the parent to be @pure +- Components **hardcoded in the template** must be foldable for the parent to be @blaze - Content **passed through slots** is handled separately and can be dynamic ### 5. Making Recommendations **For safe components:** ``` -This component is safe for @pure because it only renders static HTML and passed props. Add @pure at the top of the file. +This component is safe for @blaze because it only renders static HTML and passed props. Add @blaze at the top of the file. ``` **For unsafe components:** ``` -This component cannot use @pure because it contains [specific pattern]. The [pattern] changes at runtime and would be frozen at compile-time, causing incorrect behavior. +This component cannot use @blaze because it contains [specific pattern]. The [pattern] changes at runtime and would be frozen at compile-time, causing incorrect behavior. ``` **For borderline cases:** ``` -This component might be safe for @pure, but consider if [specific concern]. Test thoroughly after adding @pure to ensure it behaves correctly across different requests. If folding isn't possible, memoization will still provide performance benefits. +This component might be safe for @blaze, but consider if [specific concern]. Test thoroughly after adding @blaze to ensure it behaves correctly across different requests. If folding isn't possible, memoization will still provide performance benefits. ``` ## Common User Requests -### "Can I add @pure to this component?" +### "Can I add @blaze to this component?" 1. Read the component file 2. Analyze for unsafe patterns 3. Provide a clear yes/no with explanation 4. If no, suggest alternatives or modifications -### "Add @pure to my components" +### "Add @blaze to my components" 1. Find all component files (`resources/views/components/**/*.blade.php`) 2. Analyze each component individually -3. Add `@pure` only to safe components (include a line break after `@pure` ) +3. Add `@blaze` only to safe components (include a line break after `@blaze` ) 4. Report which components were modified and which were skipped with reasons ### "Optimize my Blade components" -1. Audit existing components for @pure eligibility -2. Identify components that could be refactored to be pure +1. Audit existing components for @blaze eligibility +2. Identify components that could be refactored to be foldable 3. Suggest architectural improvements for better optimization 4. Provide before/after examples ## Implementation Guidelines -### Adding @pure to Components +### Adding @blaze to Components -When adding `@pure` to a component: +When adding `@blaze` to a component: 1. **Always read the component first** to understand its structure -2. **Add @pure as the very first line** of the component file +2. **Add @blaze as the very first line** of the component file 3. **Preserve existing formatting** and structure 4. **Don't modify component logic** unless specifically requested @@ -228,7 +228,7 @@ Example edit:

{{ $title }}

{{-- After --}} -@pure +@blaze @props(['title']) @@ -241,21 +241,21 @@ When processing multiple components: 1. **Process files individually** - don't batch edits 2. **Report results clearly** - which succeeded, which failed, and why -3. **Provide summary statistics** - "Added @pure to 15 of 23 components" +3. **Provide summary statistics** - "Added @blaze to 15 of 23 components" 4. **List problematic components** with specific reasons for skipping ### Error Handling -If Blaze detects unsafe patterns in a `@pure` component, it will show compilation errors. When helping users: +If Blaze detects unsafe patterns in a `@blaze` component, it will show compilation errors. When helping users: 1. **Explain the error** in simple terms 2. **Show the problematic code** and why it's unsafe -3. **Suggest solutions** - remove @pure or refactor the component +3. **Suggest solutions** - remove @blaze or refactor the component 4. **Provide alternatives** if the optimization is important ## Testing Recommendations -After adding `@pure` to components: +After adding `@blaze` to components: 1. **Test with different props** to ensure consistent rendering 2. **Verify in different contexts** - authenticated vs guest users diff --git a/README.md b/README.md index f48c07d4..a7e686fe 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Speed up your Laravel app by optimizing Blade component rendering performance. > ⚠️ **Early stages** - This is an early-stage experimental package. APIs may change, and edge cases have yet to be worked out. Please test thoroughly and report any issues! ``` -Rendering 25,000 pure button components: +Rendering 25,000 foldable button components: Without Blaze ████████████████████████████████████████ 750ms With Blaze ██ 45ms @@ -27,16 +27,16 @@ composer require livewire/blaze ## Usage -To optimize a Blade component for performance, simply add the `@pure` directive at the top of your component file. +To optimize a Blade component for performance, simply add the `@blaze` directive at the top of your component file. -The `@pure` directive signals that your component is "pure" - meaning it has no side effects and always renders the same output for the same input (no auth checks, no database queries, no time-dependent content). Think of these as your basic UI building blocks like buttons, cards, and badges. +The `@blaze` directive signals that your component is "foldable" - meaning it has no side effects and always renders the same output for the same input (no auth checks, no database queries, no time-dependent content). Think of these as your basic UI building blocks like buttons, cards, and badges. -> **Using Flux?** All eligible Flux components are already marked with `@pure` - you don't need to do anything! Just install Blaze and enjoy the performance boost. +> **Using Flux?** All eligible Flux components are already marked with `@blaze` - you don't need to do anything! Just install Blaze and enjoy the performance boost. ```blade {{-- resources/views/components/button.blade.php --}} -@pure +@blaze @props(['variant' => 'primary']) @@ -45,17 +45,17 @@ The `@pure` directive signals that your component is "pure" - meaning it has no ``` -The `@pure` directive supports optional parameters to control different optimization strategies: +The `@blaze` directive supports optional parameters to control different optimization strategies: ```blade {{-- All optimizations enabled (default) --}} -@pure +@blaze {{-- Explicitly enable all optimizations --}} -@pure(fold: true, memo: true, aware: true) +@blaze(fold: true, memo: true, aware: true) {{-- Disable specific optimizations --}} -@pure(fold: false, memo: true, aware: false) +@blaze(fold: false, memo: true, aware: false) ``` **Parameters:** @@ -84,16 +84,16 @@ Blaze will automatically optimize it during compilation, pre-rendering the stati ## Table of contents -- [When to use @pure](#when-to-use-pure) +- [When to use @blaze](#when-to-use-blaze) - [Performance expectations](#performance-expectations) - [Debugging](#debugging) - [AI assistant integration](#ai-assistant-integration) -## When to use @pure +## When to use @blaze -The `@pure` directive tells Blaze that a component has no runtime dependencies and can be safely optimized. Only add it to components that render the same way every time they're compiled. +The `@blaze` directive tells Blaze that a component has no runtime dependencies and can be safely optimized. Only add it to components that render the same way every time they're compiled. -### The @pure litmus test +### The @blaze litmus test Ask yourself these questions about your component: @@ -101,32 +101,32 @@ Ask yourself these questions about your component: 2. **Does it work the same on every request?** (no request data, no CSRF tokens) 3. **Does it work the same at any time?** (no timestamps, no "time ago" formatting) 4. **Does it only use the props you pass in?** (no session data, no database queries) -5. **Are all child components it renders also pure?** (no dynamic components hardcoded inside) +5. **Are all child components it renders also foldable?** (no dynamic components hardcoded inside) -**If you answered YES to all questions → Add `@pure`** -**If you answered NO to any question → Don't add `@pure`** +**If you answered YES to all questions → Add `@blaze`** +**If you answered NO to any question → Don't add `@blaze`** ### Quick mental model -Think of `@pure` components as **"design system" components** - they're the building blocks that: +Think of `@blaze` components as **"design system" components** - they're the building blocks that: - Look the same for everyone - Only change based on props you explicitly pass - Could be shown in a component library without any application context Examples: buttons, cards, badges, icons, layout grids, typography components -**Not pure** : anything that's "smart" or "connected" - forms (CSRF), navigation (active states), user avatars (auth), timestamps (time), paginated tables (request state). +**Not foldable** : anything that's "smart" or "connected" - forms (CSRF), navigation (active states), user avatars (auth), timestamps (time), paginated tables (request state). -**For developers familiar with functional programming**: Think of `@pure` components like pure functions - they always produce the same output for the same input, with no side effects or dependencies on external state. +**For developers familiar with functional programming**: Think of `@blaze` components like pure functions - they always produce the same output for the same input, with no side effects or dependencies on external state. -### ✅ Safe for @pure +### ✅ Safe for @blaze These components are good candidates for optimization: ```blade {{-- Static UI components --}} -@pure +@blaze
{{ $slot }} @@ -136,7 +136,7 @@ These components are good candidates for optimization: ```blade {{-- Components that only depend on passed props --}} -@pure +@blaze @props(['size' => 'md', 'color' => 'blue']) @@ -145,15 +145,15 @@ These components are good candidates for optimization: ``` -### ❌ Never use @pure with +### ❌ Never use @blaze with -Avoid `@pure` for components that have runtime dependencies: +Avoid `@blaze` for components that have runtime dependencies: ```blade {{-- CSRF tokens change per request --}}
- @csrf + @csrf
``` @@ -161,7 +161,7 @@ Avoid `@pure` for components that have runtime dependencies: ```blade {{-- Authentication state changes at runtime --}} -@auth +@auth

Welcome back!

@endauth ``` @@ -171,7 +171,7 @@ Avoid `@pure` for components that have runtime dependencies: @props(['href']) - request()->is($href)])> + request()->is($href)])> {{ $slot }} ``` @@ -179,7 +179,7 @@ Avoid `@pure` for components that have runtime dependencies: ```blade {{-- Error bags are request-specific --}} -@if($errors->has('email')) +@if($errors->has('email')) {{ $errors->first('email') }} @endif ``` @@ -187,13 +187,13 @@ Avoid `@pure` for components that have runtime dependencies: ```blade {{-- Session data changes at runtime --}} -
Welcome, {{ session('username') }}
+
Welcome, {{ session('username') }}
``` ```blade {{-- Pagination components --}} -@props(['paginator']) +@props(['paginator'])