Hyperwire Laravel Package

Getting Started

What v2.0.0 actually is: a major bump whose only stated change is moving the package's Livewire dependency from v3 to v4. Treat it as a breaking release by proxy — the package's own public surface may be unchanged, but Livewire's is not, so every consumer app has to migrate.

First moves on an existing app:

1. Pin your current state before touching anything: composer require <package>:^1.0 in a branch, commit the lockfile, so you have a known-good rollback.
2. Check the package's composer.json require block for the Livewire constraint (^4.0) and the minimum PHP it implies. Compare against your app's PHP version and CI matrix before running the update.
3. Upgrade Livewire core first, in isolation, on a branch with the package still on ^1.0 — this separates "Livewire 4 broke my app" from "the package broke my app."
4. Then composer require <package>:^2.0 and re-publish anything the package ships: config, views, migrations, and frontend assets.
5. Clear the caches that hide stale Blade component registration: php artisan optimize:clear plus view:clear and component:clear.
6. Rebuild frontend assets (npm ci && npm run build) — Livewire's JS payload is versioned and a stale public/vendor or old bundle will produce hydration errors that look like package bugs.

Where to look first: the package's UPGRADE.md / CHANGELOG.md, then its service provider boot() method (that is where component registration and Livewire asset hooks usually live), then any published Blade views — those are the most likely place an overridden file still contains a Livewire 3-era directive.

First success criterion: one package-provided component rendering and re-rendering in a browser, plus one Livewire::test(PackageComponent::class)->assertOk() green. If both pass, the remaining work is your own components.

Implementation Patterns

Upgrade workflow (recommended shape):

• One branch per step: Livewire 4 alone → package v2 → your own components → frontend build. Never combine the package bump with an unrelated feature branch.
• Run the package's own test coverage against your app if it ships tests, and add a smoke test that mounts every component the package registers.
• Prefer a staging deploy with real users on it for one cycle before production; Livewire regressions surface in interaction (polls, modals, file uploads), not in a page load.

Day-to-day usage stays largely identical: you still register components in Blade (<livewire:... /> or the tag syntax), dispatch and listen for events, use wire:model, actions, polling, and file uploads. The package is a thin integration layer; your authoring style does not need to change just because the underlying major moved.

Testing pattern that pays for itself here:

Livewire::test(PackageComponent::class)
    ->set('field', 'value')
    ->call('save')
    ->assertHasNoErrors()
    ->assertDispatched('saved');

Keep a handful of these around package components. They catch Livewire upgrades cheaply, and they're the fastest way to confirm the v2 bump didn't regress behavior.

Integration tips:

• If you override any package views, diff them against the v2 versions — a published view is a frozen copy of a specific Livewire era.
• If the package exposes events or lifecycle hooks, assert on them in tests rather than on rendered markup; DOM assertions are the most brittle thing across Livewire majors.
• For multi-app repos, keep legacy apps on ^1.0 and migrate one app at a time. A shared internal package that requires <package>:^2.0 will force every dependent app forward at once — check your dependency graph before bumping the constraint anywhere central.

Gotchas and Tips

This is a hard break, not a soft one. v2.0.0 drops Livewire 3 support. There is no compatibility window; an app on Livewire 3 cannot use this release. Plan the constraint change as a scheduled migration, not a routine composer update.

Composer resolution pain. During the transition you'll hit conflicts where the package wants ^4.0 and something else (a third-party Livewire addon, a starter kit) still pins ^3.0. Diagnose with composer why-not livewire/livewire ^4.0 rather than reading error walls. Every Livewire plugin in your app is now a blocker to enumerate up front.

Alpine duplication. Livewire bundles Alpine. If the package or your layout also loads Alpine independently, you get "Alpine is already defined" and silently broken reactivity. Load exactly one.

Stale assets masquerade as code bugs. Hydration mismatches, 404s on the Livewire update endpoint, and "component not found" errors after an upgrade are usually a cached view, a stale public/vendor directory, or an un-rebuilt bundle. Clear and rebuild before debugging logic.

Published views are the top regression source. A Blade file you copied out of the package in 2024 still speaks Livewire 3. Either re-publish and re-apply your edits, or drop the override if you no longer need it.

Test-suite churn is expected. HTML snapshot assertions, assertSeeHtml escaping, and anything asserting on rendered internals may need updating — that is a test problem, not a package problem. Don't let it mask a real failure; review each diff rather than bulk-accepting.

Debugging ladder: Livewire::test() in a unit test (fastest, no JS) → browser with the network tab open (inspect the update payload and response) → Livewire's devtools → only then read package source. Most "package" bugs are app-side component state that Livewire 4 now validates more strictly.

Extension points to check for drift: published config keys, view overrides, custom component registration in the service provider, and any event/listener wiring. These are where a major Livewire bump leaks into your code even when the package's README looks unchanged.

Keep a documented rollback. Because the break is transitive, rolling back means reverting Livewire and the package together. Write down the exact pinned pair (livewire/livewire version + package version) that was known-good before you start.