Ecommerce Storefront Livewire Laravel Package

Getting Started

The storefront is a Livewire satellite of the ArtisanPack UI ecommerce engine — it owns no tables, so treat the engine as a hard prerequisite rather than an optional companion.

1. Confirm the baseline before installing. You need the engine at 1.1, Laravel 12 or 13, Livewire 3.6+ or 4, PHP 8.3+ with ext-intl enabled. Engine migrations, product types, and a payment gateway should already be in place — the storefront renders whatever the engine services return.
2. Install the package: composer require artisanpack-ui/ecommerce-storefront-livewire. Note the conflicts (artisanpack-ui/visual-editor below 1.8) and the security constraint (^1.0.3|^2.0) if you already depend on those.
3. Run php artisan ecommerce-storefront:install. This is the single most important step: it publishes the config, prints the Tailwind @source lines and the layout include you must paste into your app, checks that your host app has login and register routes, and warns if no payment gateway is configured. Treat every line it prints as required setup, not a suggestion.
4. Configure config/storefront.php first, before touching views. The knobs you will reach for daily are the route prefixes, routes_enabled, the layout the page controller wraps screens in, account.middleware, account.claim_requires_verified_email, and storefront.rtl_locales.
5. First use case to validate end to end: browse the catalog page, open a product, add to cart, run a guest checkout through the Stripe Payment Element driver, and land on the confirmation page. That single path exercises routes, layout wrapping, the cart drawer, currency handling, stock reservation, the one-time order token, and the SEO/meta pipeline in one pass.

Implementation Patterns

Route-first or component-first, decide per surface. The package ships full routes (configurable prefixes, killable via routes_enabled) where a page controller wraps each screen in your layout. Every screen is also a mountable Livewire component, so a common pattern is: keep the storefront routes for catalog, cart, and checkout, but disable or ignore them for account screens and mount the account components inside your existing dashboard. The standalone layout is fine for a weekend prototype; replace it with your app layout before launch so navigation, flash messages, and CSP nonces behave consistently.

Wire Tailwind before styling anything. The install command prints @source lines — those tell Tailwind 4 to scan the package's Blade views. Skip them and you get a storefront with no classes emitted and a very confusing debugging session.

Payments go through the driver registry, not through your views. Register a driver for Stripe Payment Element (3DS handled), or use the generic redirect driver for hosted pages. If you write your own gateway, implement the engine's RendersClientPayment contract and it plugs in with zero storefront changes. Card data never enters Livewire state by design — keep your integration in the browser-side Element flow and let the server only see tokens.

Checkout is composed, not forked. Pick wizard or single-page via config, then extend by registering satellite steps. A satellite step declares a server-side complete callable; unreachable steps are ignored server-side but every step is re-checked immediately before the order is placed. Write complete to be idempotent — it can be called on the "place order" pass after already succeeding on a webhook pass.

// Satellite step registration, conceptually:
// - declare the step + a server-side complete() callable
// - complete() must be safe to invoke more than once
// - the step's own validation is re-run before order placement

Bind CreatesCustomerAccounts when you need account creation to match your domain rules. The default never takes over an existing customer record for an unverified email; if your app already has a customers table with different semantics, swap the action rather than patching around it.

Extend through filters and actions, not view overrides. There are hooks for catalog filters and sorts, product sections, cart sections, checkout steps, and header actions, plus registries for purchase forms and payment drivers. Overriding a published Blade view is the last resort — it breaks on every minor release. Do use view publishing for the four editable templates the visual editor exposes (product, category, cart, checkout) and for your own layout.

Compose host pages from Blade components. x-artisanpack-ec-* covers price, price range, money, stock status, rating summary/input, address and address form, product card, gallery, swatches, quantity, category grid, search box, skeleton, empty state, account shell, and field. The field component is the one to standardize on for any custom form you build — it links a control's error and hint to the input, which is how you stay consistent with the package's error-summary behavior.

Add account navigation through AccountMenuRegistry rather than editing the account shell. This is how other satellites surface links, and it keeps your additions visible in every theme.

SEO: let the package own the storefront pages. Titles, descriptions, canonicals, Open Graph, and Product/BreadcrumbList JSON-LD are emitted for you; cart, checkout, account, and search are noindex. If artisanpack-ui/seo is installed, its schema collector prints the structured data instead — don't hand-roll a second set of tags or you'll ship duplicates.

Testing pattern: mirror the package's own Pest 4 + Playwright setup. For unit-level work, fake the engine services and the payment driver; for checkout flows, drive the real browser, because the one-time action token, the Element iframe, and focus management in the drawer are not meaningfully testable from Livewire component tests alone. Run an axe check on any screen you customize — the package does this on every screen, so a failure is almost always your override.

Gotchas and Tips

• app.url is load-bearing. Order-view links and guest order lookup URLs are built from it. A wrong APP_URL in staging produces signed links pointing at production, and the failure looks like a broken signature, not a config error. Set it per environment.
• Cache invalidation is event-driven. The category tree and filter counts are cached and cleared on catalog changes. If you import products via seeders, direct SQL, or a queue job that bypasses the engine's model events, stale counts and missing categories will persist until you clear manually. Same caution applies after bulk price or currency changes.
• Signed URLs are short-lived by design. Downloads and stream links last 10 minutes and 4 hours respectively; guest order pages use signed tokens. Don't email or cache those URLs, and check clock skew on containerized infrastructure — a few minutes of drift turns into "expired link" reports.
• Cart, checkout, and account pages send Cache-Control: no-store, private. If you front the storefront with full-page cache or a CDN rule that ignores origin headers, you will serve one shopper's cart to another. Exclude those paths explicitly and don't rely on the header alone.
• Rate limiters are shared with the engine. Cart, checkout, address, review, search, currency, order-lookup, and guest-claim actions all count toward the engine's limiters. Tune them before load testing or you'll chase phantom 429s; search-as-you-type in the header is the loudest consumer.
• Custom account.middleware groups re-run on Livewire updates. That is what makes them trustworthy for authorization, but it also means anything expensive or redirect-happy in those groups fires on every Livewire round trip. Keep guards cheap and avoid middleware that assumes a full page request.
• Double submits are handled by a signed one-time action token. Don't bypass the component's submit path (for example, by posting from your own form) or you lose that guarantee along with the step re-checks.
• Webhook-first orders are a real path. When the payment webhook places the order before the shopper returns, the shopper still lands on confirmation and the reviewed order note is preserved; fraud-held orders show a "reviewing" notice. Your confirmation-page analytics or thank-you logic must tolerate an order that already existed before the browser arrived.
• Steps lock after placement. Don't render state-changing checkout UI post-placement; the wizard won't let the shopper move anyway, so hide rather than disable.
• Guest claim requires a verified email by default. account.claim_requires_verified_email is the switch. If you turn it off, decide what an unverified claim means for order history visibility before you ship it.
• Products of uninstalled product types silently disappear from listings. When a product "vanishes," check the engine's product type installation before you debug the query layer.
• Store-owner HTML is filtered through htmLawed safe mode. Product and category descriptions cannot carry scripts or embeds; review text is stored as plain text. Tell merchandisers early instead of discovering it in a support ticket.
• Search depends on the engine's SearchProvider. Facets and header live suggestions route through it — if the provider isn't bound or is swapped, the header combobox degrades and facet counts go quiet.
• Accessibility claims need the caveat. The package targets WCAG 2.2 AA and its own suite axe-checks every screen, but known issues in artisanpack-ui/livewire-ui-components markup are documented. Read that list before committing to a compliance statement, and re-test at 320px width — the "no sideways scroll / no hidden tab stops" guarantees are the easiest to break with a custom section.
• Translations cover English, Spanish, French, and German. Publish the lang files and add your locale; also add it to storefront.rtl_locales if it is right-to-left, or layout direction won't flip.
• The package registers nothing while uninstalled, via the engine's SatelliteRegistry. If you conditionally disable it, expect account menu entries and visual-editor blocks to vanish too — that's intentional, not a bug.
• Release hygiene matters if you fork or extend. Releases verify the engine's satellite contract with --allow-empty (the storefront registers no contract implementations), and a tag needs a signed report matching the provider's VERSION and a CHANGELOG section. Keep VERSION and CHANGELOG in sync or your own tags silently produce no release.