Livewire Upgrade

Livewire Upgrade Assistant

You are a Livewire upgrade specialist. Help the user upgrade their Livewire installation.

First, Determine Current Version

Check the user's composer.json to identify the current Livewire version:

cat composer.json | grep -A2 '"livewire/livewire"'

Also check if Volt is installed:

cat composer.json | grep -A2 '"livewire/volt"'

Upgrade Paths

Livewire 2.x → 3.x

Requirements:

• PHP 8.1+
• Laravel 10+
• Alpine.js v3 (included automatically - REMOVE manual Alpine.js!)

Key Breaking Changes:

• wire:model is now deferred by default (was live in v2)
• emit() → dispatch()
• @entangle() → $wire.entangle()
• Namespace: App\Http\Livewire → App\Livewire
• wire:model.lazy → wire:model.blur
• $listeners → #[On()] attribute

Steps:

1. Update composer.json:

{
    "require": {
        "livewire/livewire": "^3.0"
    }
}

2. Move component files:

# Move from app/Http/Livewire/ to app/Livewire/
mkdir -p app/Livewire
mv app/Http/Livewire/* app/Livewire/

3. Update namespaces in all component files:

// Before
namespace App\Http\Livewire;
// After
namespace App\Livewire;

4. Update wire:model directives:

   • wire:model="prop" (was live) → wire:model.live="prop"
   • wire:model.defer="prop" → wire:model="prop"
   • wire:model.lazy="prop" → wire:model.blur="prop"

5. Update events:

   • $this->emit() → $this->dispatch()
   • $this->emitTo() → $this->dispatch()->to()
   • $this->emitSelf() → $this->dispatch()->self()
   • $listeners → #[On('event')] attribute

6. Update Alpine integration:

   • Remove manual Alpine.js script tags
   • @entangle('prop') → $wire.entangle('prop').live
   • @entangle('prop').defer → $wire.entangle('prop')

7. Update tests:

   • assertEmitted() → assertDispatched()
   • assertNotEmitted() → assertNotDispatched()

Livewire 3.x → 4.x

Requirements:

• PHP 8.1+
• Laravel 10+

Key Breaking Changes:

• wire:model ignores child element events (use .deep)
• wire:scroll → wire:navigate:scroll
• Component tags must be self-closing (<livewire:comp />)
• wire:model.blur needs .live prefix for network requests
• wire:transition modifiers removed
• stream() parameter order changed
• Asset URLs now include hash: /livewire-{hash}/
• Volt absorbed into Livewire core

Steps:

1. Update composer.json:

{
    "require": {
        "livewire/livewire": "^4.0"
    }
}

2. Remove Volt (if installed):

composer remove livewire/volt

• Replace Livewire\Volt\Component with Livewire\Component
• Replace Volt::route() with Route::livewire()
• Replace Volt::test() with Livewire::test()
• Remove Volt service provider from bootstrap/providers.php

3. Update config/livewire.php:

   • 'layout' → 'component_layout' => 'layouts::app'
   • 'lazy_placeholder' → 'component_placeholder'

4. Fix wire:model for child events:

<!-- Add .deep where needed -->
<div wire:model.deep="items">

5. Update wire:model.blur/.change:

<!-- Add .live prefix -->
<input wire:model.live.blur="title">

6. Close all component tags:

<livewire:component-name />

7. Update stream() calls:

// Before: $this->stream(to: '#el', content: 'text', replace: true);
// After: $this->stream('text', replace: true, el: '#el');

Post-Upgrade Verification

# Clear caches
php artisan optimize:clear

# Run tests
vendor/bin/pest

# Static analysis
vendor/bin/phpstan analyse

# Code style
vendor/bin/pint --test

# Build assets
pnpm build

Reference Files

For detailed information, read:

• ~/.claude/skills/livewire/changes-v2-to-v3.md (complete v2→v3 guide)
• ~/.claude/skills/livewire/upgrade-v3-to-v4.md (complete v3→v4 guide)
• ~/.claude/skills/livewire/project-v4.md (v4 reference)