Livewire Molecule Laravel Package

Getting Started

v2.1.0 is a compatibility release, not a feature release. Before you write a line of integration code, confirm you are on a supported stack, because this version will refuse to install on the stack most people are still running.

1. Check your constraints first. Open your composer.json and verify:

• laravel/framework → ^11.0 or ^12.0 or ^13.0 (v2.1.0 drops ^10.0)
• livewire/livewire → ^4.0 (v2.1.0 drops ^3.0)

If you are on Laravel 10 or Livewire 3, stay on the previous 2.0.x line. There is no shim, no deprecated fallback — this is a hard cut.

2. Install.

composer require <vendor>/<package>:^2.1 --with-all-dependencies

Use -W (--with-all-dependencies). Without it, Composer will happily report a conflict against a transitive Laravel 10 constraint and leave you guessing which package is holding you back.

3. Publish and migrate, if applicable.

php artisan vendor:publish --provider="<Vendor>\<Package>\<Package>ServiceProvider"
php artisan migrate

Check whether the publish tags are split (--tag=config, --tag=migrations, --tag=views). Most packages of this shape do split them, and you usually do not want to republish views.

4. Where to look first, in order:

• composer.json in the package — the real source of truth for what "Laravel 13 support" means (a require bump, or actual code changes?)
• UPGRADE.md / CHANGELOG.md — check whether the Livewire 4 drop was accompanied by component API changes
• The service provider (src/*ServiceProvider.php) — what is registered, and whether anything is conditional on environment
• config/<package>.php after publishing — the knobs you will actually touch

5. First use case: render the package's Livewire component on a throwaway route and confirm it mounts, hydrates, and responds to a wire:model round-trip. That single smoke test catches the majority of Livewire 3→4 breakage (lifecycle hook renames, $wire behaviour changes) faster than reading release notes.

Implementation Patterns

Stage the upgrade in isolation. Because this release raises two floors at once (framework and Livewire), do not bundle it with feature work. Branch, bump composer.json, run composer update -W, then run your full suite. If it fails, you want a clean diff to bisect.

Use a CI matrix, not a single job. With Laravel 11/12/13 now in the support window, run at least laravel/framework:^11 and ^12 in CI, and treat 13 as an allowed-failure job until it is generally available on your infra. This is the cheapest way to catch a future 2.2.0 regression before it reaches main.

Wire the new test helpers into your own suite. v2.1.0 adds test methods aimed at local development. The correct pattern is to call them from your own feature tests rather than duplicating fixtures:

it('renders the widget', function () {
    // package-provided helper sets up auth/tenant/state
    $this->setUpPackageContext();

    Livewire::test(WidgetComponent::class)
        ->assertSee('...');
});

If they are traits, add them to tests/Pest.php or your TestCase once, globally. If they are plain static helpers, keep them behind a tests/-only import so they never leak into application code.

Feature-flag the integration, not the package. If you are shipping to a mixed fleet where some apps are still on Livewire 3, keep two application branches rather than trying to abstract the package version away. Version-conditional service container bindings age badly.

Treat the config file as the extension point. Publish it, commit it, and change behaviour there rather than subclassing package internals. When 2.2.0 lands you will re-publish and diff one file instead of reconciling a fork.

Gotchas and Tips

• "Adds support for Laravel 13" is a claim to verify. Laravel 13 is ahead of general availability. Check whether the package's require says ^13.0 against a dev/RC constraint, and pin exact versions in production until you have CI evidence. A constraint bump is not the same as tested compatibility.
• Dropping Livewire 3 is the sharp edge, not Laravel 10. Laravel 10 → 11 is mostly a config/skeleton change you can absorb. Livewire 3 → 4 touches component lifecycle, wire: directive semantics, and hydration. If your tests pass but the browser misbehaves, suspect hydration before you suspect the package.
• Test methods "for local development" may ship in production. Verify where they live: check the package's autoload vs autoload-dev sections. If they are in autoload, they are in your production autoloader — harmless but worth knowing, and worth confirming they are not auto-registered as routes or commands.
• Composer conflict messages are misleading here. A Laravel 10 app that requires this package will report a conflict on some other package's constraint, not on the package itself. Always resolve with composer why-not <vendor>/<package> 2.1.0 to see the real blocker.
• Debug the binding, not the template. When a Livewire component from a package fails to render, the cause is usually a missing container binding or an unpublished config, not a view problem. php artisan tinker and resolve the package's main class directly — you will get a clearer exception than the Livewire render error.
• Re-publish config after major bumps. New keys in 2.1.0 will not appear in your already-published config/ file. vendor:publish --force into a scratch branch and diff — do not force-publish onto your working copy.
• Extension points to prefer: the published config, container bindings via the service provider, and published views. Everything else is package internals and will break on the next minor.