Livewire Starter Kit Laravel Package

Getting Started

This is a starter kit, not a library you composer require — the intended workflow is cloning/forking the repo into your own project (or using lunarphp/lunar's installer which scaffolds from it). Do not try to composer require lunarphp/livewire-starter-kit and expect an app.

Minimal steps:

1. Clone the repo (or use the Lunar installer with this starter as the base).
2. composer install && npm install
3. Copy .env.example → .env, set APP_KEY, database, and Lunar API credentials (LUNAR_* env vars — see note in Gotchas about env naming changes).
4. php artisan migrate --seed — the ProductSeeder seeds products/variants for the demo storefront.
5. npm run dev && php artisan serve.

Where to look first:

• app/Http/Livewire/ — the Livewire components for product, cart, checkout, search.
• resources/views/livewire/ — the corresponding Blade views (homepage, navigation, product, cart, checkout, search, confirmation).
• routes/web.php — storefront routes and how they map to the components.
• config/lunar/ — Lunar configuration (publishing via php artisan vendor:publish --tag=lunar).

First use case worth tackling: get the demo storefront running end-to-end (browse → add to cart → checkout → confirmation) on the seeded data. That exercises nearly every piece of the starter.

Implementation Patterns

Extend the components rather than editing in place where possible. If you're forking, keep custom logic in subclasses or traits so you can diff against upstream releases. The starter gets upstream updates (see this 1.0.0-alpha.1 changelog — dozens of styling and bug fixes), and merging gets painful if you've rewritten core components.

Treat styling as disposable. This release is overwhelmingly styling changes (style/homepage, style/navigation, style/product, style/cart, style/checkout, style/search, etc.). Plan to replace the Tailwind classes wholesale with your brand — don't try to cherry-pick styling commits.

Livewire component composition for cart/checkout. The typical pattern in this kit: a cart component listens for addToCart events emitted by product/variant components. Wire additional listeners in getListeners() when adding cross-component behavior (e.g. "add to cart from product card" in a listing page). Note PR #56 removed a duplicated listener — verify you don't reintroduce it when customizing.

Variant selection and media. Variant selection drives which media is displayed (see PR #50 hotfix "Variant media not switching"). Follow the existing pattern: emit variant-changed, swap media on the component, rely on the computed property rather than mutating in the view.

Validation on cart mutations. addToCart now validates stock and quantity (PR #74). Keep validation inside the Livewire method — don't push it to the form request layer, since Livewire actions don't go through HTTP form requests.

Checkout address saving. The checkout flow supports "save address" (PR #54). If you're integrating with Lunar's customer address book, extend the checkout component rather than duplicating logic — the flow already handles persistence.

Integrate with Lunar via its models and pipelines, not by reimplementing: Lunar\Models\Product, Cart, Order. The starter already wires these into Livewire — when adding features, lean on Lunar's services so you don't fight the state that's already tracked (stock, pricing, tax, shipping options).

Gotchas and Tips

Version alignment is critical. This is 1.0.0-alpha.1 supporting Lunar 1.x (PR #86 "Support of Lunar 1.x"). Mixing Lunar 0.8/0.7-era code will break — the namespace updates (PR #44) and dependency refreshes (PR #48) mean old examples from blog posts/tutorials won't apply. Pin your lunarphp/lunar version to match.

1.0.0-alpha.1 is pre-release. Expect churn. Don't production-deploy without pinning a commit SHA or forking at a known-good state, and audit the diff between alpha and stable before upgrading.

Meilisearch is no longer included (PR #46). If you follow older docs expecting Meilisearch search, you'll need to wire it yourself. The search component here is a simpler implementation — treat it as a template, not a full-featured search.

PHP 7.4 is the floor (PR #55), Laravel 9.x (PR #61). If you're on PHP 8.x this is fine, but if you're on PHP 7.3 you're blocked, and if you're on Laravel 10 you may hit composer resolution issues.

Env naming changed (PR #54 "Checkout Save Address & Env Naming"). Copy .env.example fresh rather than reusing an older .env — mismatched variable names silently leave config null (e.g. API keys, shipping settings). This is a common source of "checkout is broken" reports.

Images breaking after customization — PRs #51 and #52 fixed broken cart/checkout images. The fix hinges on the media conversion being registered on the Lunar model. If you replace images with your own attributes, ensure the media relationship and conversions still resolve, or you'll reproduce those bugs.

addToCart requires stock info on variants. PR #74 removed the duplicate stock key from ProductSeeder and added validation. If you re-seed from your own script, model stock per-variant (not per-product) — otherwise quantity validation fails or over-sells.

Install process historically fragile (PR #49 "Issues with the install process"). If install fails, check Node version first (old Tailwind/Vite toolchain) and then composer.json conflicts. The Hotfix - Freshen up dependencies (#48) exists because of this — don't downgrade dependencies to match stale tutorials.

Lando config exists (PR #18) but is optional; ignore it if you're on a standard Sail/Valet/Homestead setup.

Extension points to favor: Livewire component events (for cross-widget communication), Lunar's pipeline hooks (for tax/shipping/cart calculations), and Blade component slots for layout variants. Avoid subclassing Lunar models — the starter doesn't, and doing so makes upstream merges harder.

No published config or service provider of its own — the kit's "configuration" is really config/lunar/* (published from Lunar core) plus env vars. Don't go looking for a config/livewire-starter-kit.php.