Livewire Development

When to Apply

Activate this skill when:

• Creating or modifying Livewire components
• Using wire: directives (model, click, loading, sort, intersect)
• Implementing islands or async actions
• Writing Livewire component tests

Documentation

Use search-docs for detailed Livewire 4 patterns and documentation.

Project Conventions

These conventions are specific to this project. When proposing changes to these conventions, update .ai/guidelines/project-guidelines.md.

Authorization

Use $this->authorize() with policies in Livewire action methods. Use #[CurrentUser] for injecting the authenticated user instead of the Auth facade.

php
1// Good
2use Illuminate\Container\Attributes\CurrentUser;
3
4public function saveReport(#[CurrentUser] User $user): void
5{
6    $this->authorize('create', [InjuryReport::class, $this->injury]);
7    // ...
8}
9
10// Bad
11public function saveReport(): void
12{
13    if (Auth::id() !== $this->injury->user_id) {
14        return;
15    }
16    // ...
17}

Authorize at the action level (e.g. saveReport, deleteReport), not in mount(). This keeps authorization close to the mutation and leverages policies consistently.

Mount Methods

Omit mount() when it only assigns typed public properties — Livewire handles this automatically.

Basic Usage

Creating Components

bash
1
2# Single-file component (default in v4)
3
4{{ $assist->artisanCommand('make:livewire create-post') }}
5
6# Multi-file component
7
8{{ $assist->artisanCommand('make:livewire create-post --mfc') }}
9
10# Class-based component (v3 style)
11
12{{ $assist->artisanCommand('make:livewire create-post --class') }}
13
14# With namespace
15
16{{ $assist->artisanCommand('make:livewire Posts/CreatePost') }}

Converting Between Formats

Use php artisan livewire:convert create-post to convert between single-file, multi-file, and class-based formats.

Component Format Reference

Single-File Component Example

php
1<?php
2use Livewire\Component;
3
4new class extends Component {
5    public int $count = 0;
6
7    public function increment(): void
8    {
9        $this->count++;
10    }
11}
12?>
13
14<div>
15    <button wire:click="increment">Count: @{{ $count }}</button>
16</div>

Livewire 4 Specifics

Key Changes From Livewire 3

These things changed in Livewire 4, but may not have been updated in this application. Verify this application's setup to ensure you follow existing conventions.

• Use Route::livewire() for full-page components; config keys renamed: layout → component_layout, lazy_placeholder → component_placeholder.
• wire:model now ignores child events by default (use wire:model.deep for old behavior); wire:scroll renamed to wire:navigate:scroll.
• Component tags must be properly closed; wire:transition now uses View Transitions API (modifiers removed).
• JavaScript: $wire.$js('name', fn) → $wire.$js.name = fn; commit/request hooks → interceptMessage()/interceptRequest().

New Features

• Component formats: single-file (SFC), multi-file (MFC), view-based components.
• Islands (@island) for isolated updates; async actions (wire:click.async, #[Async]) for parallel execution.
• Deferred/bundled loading: defer, lazy.bundle for optimized component loading.

New Directives

• wire:sort, wire:intersect, wire:ref, .renderless, .preserve-scroll are available for use.
• data-loading attribute automatically added to elements triggering network requests.

Best Practices

• Always use wire:key in loops
• Use wire:loading for loading states
• Use wire:model.live for instant updates (default is debounced)
• Validate and authorize in actions (treat like HTTP requests)

Configuration

• smart_wire_keys defaults to true; new configs: component_locations, component_namespaces, make_command, csp_safe.

Alpine & JavaScript

• wire:transition uses browser View Transitions API; $errors and $intercept magic properties available.
• Non-blocking wire:poll and parallel wire:model.live updates improve performance.

For interceptors and hooks, see reference/javascript-hooks.md.

Testing

php
1Livewire::test(Counter::class)
2    ->assertSet('count', 0)
3    ->call('increment')
4    ->assertSet('count', 1);

Verification

1. Browser console: Check for JS errors
2. Network tab: Verify Livewire requests return 200
3. Ensure wire:key on all @foreach loops

Common Pitfalls

• Missing wire:key in loops → unexpected re-rendering
• Expecting wire:model real-time → use wire:model.live
• Unclosed component tags → syntax errors in v4
• Using deprecated config keys or JS hooks
• Including Alpine.js separately (already bundled in Livewire 4)