Livewire Gloom Laravel Package

Getting Started

luttje/livewire-gloom is a Livewire companion package: its release line is versioned in lockstep with Livewire itself, so the major version you install is dictated by the Livewire major you already run. 4.0.0 exists to pair with Livewire 4; 3.3.3 is the last line that pairs with Livewire 3.

Minimal path:

1. Check what you're on before touching anything:

   composer show livewire/livewire | grep versions
   

2. Install the matching line — do not "just upgrade":

   # Livewire 4 project
   composer require luttje/livewire-gloom:^4.0
   # Livewire 3 project (stay here for now)
   composer require luttje/livewire-gloom:^3.3
   

3. Publish whatever the package ships (config/views/assets), then commit the published output so you can diff it on the next major:

   php artisan vendor:publish --provider="Luttje\LivewireGloom\LivewireGloomServiceProvider"
   

4. First use case: drop the package's Blade/Livewire components into one existing Livewire view — a single screen, not a whole feature — and confirm rendering, asset loading, and any wire: interactivity in the browser before wiring it into anything else.

Where to look first: the package's README and composer.json on the 4.0.0 tag (the constraint tells you more about compatibility than the release notes do), then the diff of src/ between 3.3.3 and 4.0.0.

Implementation Patterns

Pin by Livewire major, upgrade in lockstep. Treat the two version numbers as a single unit. A useful habit is a composer.json constraint pair plus a CI matrix job that proves the pair installs together:

"require": {
    "livewire/livewire": "^4.0",
    "luttje/livewire-gloom": "^4.0"
}

Upgrade in a branch, behind a feature flag. Because the release explicitly disclaims stability, gate the new components behind a config flag or a Blade conditional so you can flip back without a redeploy of the whole UI.

Wrap the package's components in your own. Create thin app-level wrappers (resources/views/components/ui/*.blade.php) that forward to the Gloom components. When the next major lands, you edit one wrapper file per component instead of grepping every view. This is also where you normalise prop names and add your own defaults.

Override views rather than editing vendor. If the package allows view publishing/overriding, put overrides under resources/views/vendor/... and record which files you've overridden in a short list in the repo. Every major bump, diff your overrides against the newly published originals.

Test at the Livewire level, not just the HTTP level. Livewire component packages break in ways HTTP assertions don't catch. Use Livewire::test() for anything interactive, and add a smoke test that renders each component you actually use — that's your regression net for a major bump.

Stage the rollout. Install 4.0.0 on a branch, run the full suite, then ship to a staging environment and click through the specific screens that use the package. Only then merge.

Gotchas and Tips

• Major alignment is not a stability claim. The release notes say this outright. Treat 4.0.0 as a compatibility marker with beta-level confidence, and don't let "4.0.0" read as "mature" in your upgrade planning.
• The changelog contains no application-code entries. Every listed PR is a GitHub Actions dependency bump (ramsey/composer-install, nick-fields/retry, dependabot/fetch-metadata) — CI plumbing that never reaches your vendor/ directory. The actual consumer-facing change is almost certainly the Livewire constraint in composer.json. Read that diff directly; don't infer behaviour from the notes.
• Debugging install conflicts: composer why-not luttje/livewire-gloom ^4.0 and composer why-not livewire/livewire ^4.0 will name the exact package holding you back. Mismatched majors here fail at install time, not runtime, which is the good outcome.
• Re-publish published assets after the bump. Published config and views from 3.x don't update themselves. Re-run vendor:publish --force into a scratch directory and diff before overwriting anything.
• Watch for Livewire 4's own breaking changes. Since the package inherits Livewire's major, most upgrade pain will come from Livewire itself rather than Gloom. Work through Livewire's upgrade guide first, then layer this on top — don't debug both at once.
• Extension points to keep handy: the service provider (for config defaults and component registration), view overrides, and any config file the package publishes. Those three are where you customise without forking.
• Low release cadence is a risk signal. Three dependabot PRs and a version bump make up the entire release. Budget for the possibility of slow upstream fixes, and keep your wrappers thin enough that forking or swapping the package stays cheap.