Resources Laravel Package

Getting Started

1. Verify your baseline before installing. v3.0.0 is a coordinated major bump that targets Livewire 4. Confirm your app is already on Livewire 4 (composer show livewire/livewire) and that your PHP/Laravel versions satisfy both Livewire 4 and this package’s new constraints. If you are still on Livewire 3, stay on the package’s 2.x line.
2. Install the new major explicitly. Use composer require vendor/package:^3.0 rather than a bare composer update, so you see the resolution conflict immediately if Livewire 4 is not yet in place.
3. Look first at three places: the package’s UPGRADE.md (or release notes), its service provider, and any published config file. The service provider tells you what is auto-registered and whether Livewire component namespaces or Blade directives are registered for you.
4. First use case: integrate the package into one existing Livewire component, render it in a Blade view, and exercise one round-trip (initial render plus one wire:model update or action call). That single path exposes most Livewire 4 compatibility issues before you roll the upgrade across the app.

Implementation Patterns

• Treat the package major as paired with the Livewire major. Upgrade Livewire and this package in the same branch/PR. Do not try to upgrade one, run the suite, and then upgrade the other; the failure modes overlap and become hard to attribute.
• Component-first integration. Add the package’s trait, attribute, or base class to Livewire components rather than wrapping package behavior in ad-hoc Blade includes. This keeps lifecycle hooks and state syncing inside Livewire’s request cycle.
• Keep package-managed state out of public Livewire properties where possible. If the package exposes its own state object or store, bind to it via the package API and use computed properties or explicit setters. Avoid duplicating it into public properties that Livewire will hydrate on every request.
• Use Livewire 4’s event API for cross-component communication. If the package dispatches events, listen with the Livewire 4 syntax and verify payload shape in a test. Event names and payloads are common places for a major-version package to make silent changes.
• Test with Livewire::test() at the component boundary. Assert that the package renders, that actions mutate state, and that validation errors surface. This is more valuable than unit-testing package internals because it exercises the Livewire 4 hydration path.
• Upgrade workflow: create an upgrade branch, bump both packages, run composer update --with-all-dependencies, clear config/view caches, run the full test suite, then manually smoke-test one page per package integration point (form, table, modal, etc.).

Gotchas and Tips

• Livewire 3 and Livewire 4 cannot coexist. Composer will resolve to one major. If another dependency pins Livewire 3, you will get a resolution failure; use composer why-not livewire/livewire 4 to find the blocker.
• Asset registration may have changed. Livewire 4 revises how frontend assets are loaded. If you previously relied on @livewireStyles / @livewireScripts or on the package publishing its own JS, verify the new inclusion path in the upgrade guide and check the browser console for duplicate or missing Alpine/Livewire initialization.
• Config caching hides publish-time changes. After publishing or editing the package config, run php artisan config:clear (and config:cache in production). Stale cached config is the most common cause of “the package ignores my settings” after a major upgrade.
• Component namespace and class naming can shift in a major. If the package registers Livewire components, confirm the namespace still matches your usage. Prefer the package’s documented component aliases over hard-coded class names.
• Debug with the Livewire request, not just the rendered HTML. Use the browser network panel to inspect the Livewire update payload and response, and enable Livewire’s debug/devtools support locally. Package-related hydration errors usually appear as missing public properties or failed method calls in that payload.
• Watch deprecations, not only errors. Run the suite with deprecation reporting enabled and check storage/logs/laravel.log after smoke tests. Livewire 4 may deprecate lifecycle hooks or directives that the package still supports for one major cycle.
• Extension points to check before forking: published views, config, macros, and custom Blade directives. If the package publishes views, re-publish and diff them; major versions often rewrite templates to match new Livewire markup.