Hearth Laravel Package

Getting Started

1. Install the package into a Laravel app that already runs Livewire 3 (this release targets livewire/livewire:^3.0):

   composer require fluid-project/hearth
   

2. Publish what's publishable — check for config, migrations, and views before writing any app code:

   php artisan vendor:publish --provider="FluidProject\Hearth\HearthServiceProvider"
   

   Read config/hearth.php first; it's usually where the package's defaults, component namespace, and feature flags live.

3. First use case — drop a Hearth component into a Blade view and let Livewire drive it:

   <livewire:hearth::your-component />
   

   Since v4.1.0 the package registers against Livewire v3's component namespace resolution, so you should not need to manually alias classes in a service provider.

4. Sanity check the version matrix before anything else: Hearth 4.1.x ↔ Livewire 3.x ↔ Laravel 10/11. Mixing Livewire 2 with this release is the most common first-run failure (see Gotchas).

Implementation Patterns

• Livewire-first composition. Treat Hearth components as ordinary Livewire v3 components: pass data via mount params, use wire:model for two-way binding, and dispatch/listen with $this->dispatch() from the PHP side and Livewire.on() on the JS side. Do not reach for package-specific event buses unless documented.

• Embedding inside existing Livewire trees. Because v4.1.0 aligns with Livewire v3, nested Hearth components inherit the v3 lifecycle and Alpine 3 integration. When a parent Livewire component re-renders, nested Hearth children re-render normally — keep state in the parent and pass read-only props down where possible.

• Progressive enhancement workflow. Build the Blade/HTML form or list first, make it work without JS, then wire it up with wire:*. This keeps accessibility and the "no-JS fallback" story intact, which is the main reason to reach for this package over hand-rolled Livewire.

• Testing pattern. Use Livewire's test helpers rather than HTTP-level tests:

  Livewire::test(HearthComponent::class)
      ->set('field', 'value')
      ->call('submit')
      ->assertDispatched('hearth-submitted');
  

• Feature-flag via config. Gate optional behaviour (e.g. auto-registration, asset injection) through config/hearth.php so package upgrades don't silently change runtime behaviour.

• Customising over forking. Publish views to resources/views/vendor/hearth and override them; this survives upgrades far better than editing vendor/ directly.

Gotchas and Tips

• Livewire v3 is now a hard requirement. The headline of v4.1.0 is Livewire v3 support (#196). If your app is still on Livewire 2, either stay on the previous Hearth minor or upgrade Livewire first — Composer will otherwise resolve to an unexpected combination or refuse to install.
• Livewire 2 → 3 behavioural drift. If you're upgrading Hearth and Livewire together, audit the package's components for v3 changes: component registration/locations, $emit→$dispatch semantics, Alpine 3 (no more Alpine 2 plugins), and the new asset injection model (@livewireStyles/@livewireScripts placement changed in v3). Symptoms usually appear as "component not found" or double-bound inputs.
• No automated upgrade path in the notes. The 4.1.0 changelog is a single feature commit, so re-run your app's Hearth-dependent tests after the bump — don't assume a no-op.
• Composer conflicts during upgrade. If composer update hangs or picks an odd version, constrain explicitly: "fluid-project/hearth": "^4.1" alongside "livewire/livewire": "^3.0". A composer why fluid-project/hearth call quickly reveals what's forcing the resolution.
• Debugging Livewire integration. Use Livewire::component() boot checks and the browser's Livewire devtools; most "Hearth component does nothing" reports are a missing layout or a component registered under the old v2 namespace.
• Extension points to know. The service provider (component registration, config merge), published views (per-component overrides), and the config file (feature flags, namespace, asset toggles). Prefer these over subclassing internals — v4.1.0 shows the package tracks Livewire internals, so subclassing is fragile across minors.
• Keep an eye on the pin. Because v4.1.0's only change is Livewire v3 compatibility, it's essentially an ecosystem-alignment release; pin to ^4.1 and re-run the test suite on each minor.