# Livewire Upgrade

> Upgrade Livewire versions (v2→v3 or v3→v4). Handles breaking changes, wire:model, events, Alpine.js, and new features.

- Skill: `joaopaulolndev/livewire-upgrade` (Agent Skill)
- Install (CLI): `npx skillmds@latest add joaopaulolndev/livewire-upgrade`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joaopaulolndev/livewire-upgrade/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: joaopaulolndev (https://skillmd.com/u/joaopaulolndev)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/joaopaulolndev/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:

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

Also check if Volt is installed:
```bash
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:**
```json
{
    "require": {
        "livewire/livewire": "^3.0"
    }
}
```

2. **Move component files:**
```bash
# 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:**
```php
// 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:**
```json
{
    "require": {
        "livewire/livewire": "^4.0"
    }
}
```

2. **Remove Volt (if installed):**
```bash
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:**
```blade
<!-- Add .deep where needed -->
<div wire:model.deep="items">
```

5. **Update wire:model.blur/.change:**
```blade
<!-- Add .live prefix -->
<input wire:model.live.blur="title">
```

6. **Close all component tags:**
```blade
<livewire:component-name />
```

7. **Update stream() calls:**
```php
// Before: $this->stream(to: '#el', content: 'text', replace: true);
// After: $this->stream('text', replace: true, el: '#el');
```

## Post-Upgrade Verification

```bash
# 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)