Starter Kits Laravel Package

Getting Started

shopper/starter-kits is not a runtime dependency — it's a registry plus a manifest convention (shopper-kit.yaml) consumed by the Shopper CLI. Nothing here ships to production; the artifact you get is a one-time file copy into your app. Read it as an onboarding/distribution mechanism, and judge the kit you install on its own merits.

Prerequisites

• A Laravel app with Shopper already installed and migrated. The kit is the last mile, not the platform — if Shopper isn't in yet, size the Shopper evaluation first.
• Node/Vite toolchain, and Stripe test keys if you want checkout working on day one.

Where to look first

1. The registry table in README.md — pick a kit by frontend, not by description. The three official kits are the same commerce surface with different rendering layers.
2. The kit repo itself (shopperlabs/livewire-starter-kit, shopperlabs/vue-starter-kit, shopperlabs/react-starter-kit), not this repo. This repo only tells you what exists.
3. The kit's shopper-kit.yaml before you run anything. It declares files to copy, dependencies to install, and post-install commands — all of which execute with your app's privileges.
4. docs.laravelshopper.dev for the underlying Shopper models (zones, currencies, carts, orders).

Minimal install

# in a Laravel app with shopper installed
php artisan shopper:kit:install shopperlabs/livewire-starter-kit

# review what the manifest did, then finish the app
php artisan migrate
npm install && npm run build
php artisan serve

Do this on a fresh branch or throwaway clone the first time. Commit the pre-install state so you can diff exactly what landed.

First use case

Pick the Livewire kit if you want the shortest path to a clickable storefront: product listing → product page → add to cart → checkout (Stripe test mode) → account/order history. That single vertical slice tells you almost everything about Shopper's ergonomics within a day or two.

Note: releases up to v1.0.x described a single Breeze-style scaffold. v1.1.0 pivoted to a community-driven registry with multiple kits. Any tutorial or blog post referencing "the Shopper starter kit" pre-v1.1 is describing a different layout — trust the CLI and the manifest, not old walkthroughs.

Implementation Patterns

Treat the scaffold commit as a tagged baseline. Immediately after install:

git add -A
git commit -m "chore: initial scaffold from shopperlabs/livewire-starter-kit v1.1.0"
git tag scaffold-baseline

Because there is no upstream patch channel for installed code, this tag is your only reliable diff anchor when you want to pull in a later kit release or a Shopper upgrade.

Keep domain logic out of kit-owned files. The kit copies components, routes, and views into your app. Put your business rules (pricing rules, shipping calculators, B2B gating) in app/ services and actions that the kit views call, rather than inlined in the copied Livewire components. That way a kit rebuild or a future headless frontend doesn't discard your differentiation.

Centralize money handling. v1.0.2 fixed a multiplication bug in the pricing helper — a signal that price math lives in one small helper you should own deliberately. Wrap it in your own Money/Price service, format in one place, and write unit tests around minor-unit conversion. Every cart, checkout, and order view will depend on it.

Multi-currency zones are configuration, not code. v1.0.1 hid the zone selector when no zones are available and added collections to the home page. In practice:

• Seed zones and currencies in a seeder as part of your project setup, not by hand in the admin.
• Make the storefront resilient to "no zone matched" — assert the selector disappears and the page still renders, because the kit already treats that as a first-class state.
• If you add currency switching, route it through Shopper's zone resolution rather than a bespoke cookie.

Use the kit's feature tests as a smoke suite. v1.0.0 added feature tests; extend them rather than replacing them. A minimum suite for your own work:

Building an internal kit is the highest-leverage pattern. If you ship more than one Shopper project, fork the official kit you like, strip it to your conventions, and publish it to a private VCS repo with your own shopper-kit.yaml. That turns setup into php artisan shopper:kit:install yourvendor/your-kit and gives you a place to encode project shape (folder layout, base layout with the admin bar, config defaults). Keep a CHANGELOG.md in your kit — you'll be the only maintainer of it.

Frontend choice is a fork in the road, not a theme toggle.

• Livewire + Alpine — lowest friction for a Blade-first Laravel team; server-rendered, minimal JS toolchain.
• Inertia + Vue 3 / React 19 — Tailwind v4 and Wayfinder typed routes; better if you want an SPA feel or already have Vue/React skills. Wayfinder means generated route helpers are a build artifact — run the generator in dev and CI, and don't commit stale output.

Pick one and standardize. Maintaining two storefront frontends against one Shopper backend is a cost with no offsetting benefit at MVP scale.

Wire the install into CI rather than letting each dev run it. For internal kits, install into a clean container and run the smoke suite. That catches manifest drift (a file that moved, a post-install command that now fails) before it becomes five developers' problem.

Gotchas and Tips

The stars belong to the registry, not the storefront. 17 stars and zero dependents describe a thin, single-maintainer index. In any security or procurement review, assess the specific kit repo and Shopper itself separately — conflating them mis-states both the risk and the maturity.

You own the code, which means you own the CVEs. "Scaffold, not theme" is the deal: no upstream pushes you fixes. When Livewire, Laravel, or Shopper ships a breaking change, remediation is your ticket. Budget a recurring upgrade line item and assign an owner who watches release notes for all three repos plus the kit.

Review shopper-kit.yaml before first install. Post-install commands run with your application's privileges. Run the first install in a clean container or a throwaway branch, read the manifest, and only then run it against a repo you care about. Never install a third-party registry kit unreviewed.

Installs target the app root, not vendor/. Good news: no Composer conflicts. Bad news: copied routes, views, and configs can collide with existing ones, and a careless install over a mature app will overwrite files. Install early in a project's life; if you must install late, use git status immediately after and reconcile manually.

Deleting what you don't need is fine — until it isn't. Trimmed a component? Check for references from routes, nav partials, and the base layout (v1.0.4 and v1.0.5 both touched config and the base layout, so those files are live wiring). grep the class/view name before removing.

Tailwind v4 in the Inertia kits is not Tailwind v3. Different PostCSS/Vite configuration and different utility semantics. Don't copy snippets from a v3 project into a v4 kit, and don't share a Tailwind config between an Inertia kit project and an older Blade project.

Wayfinder route helpers go stale silently. If generated route functions reference a route you renamed, you get runtime errors, not build errors. Regenerate after any route change and add the generation step to your dev and build scripts.

Zone selection being hidden is correct behavior, not a bug. If a visitor's country matches no zone, the selector disappears — verify your checkout path degrades gracefully rather than 500ing on a null zone. Test with a request from an unconfigured country early; it's the most common "works on my machine" storefront failure.

Prices are minor-unit integers. Formatting and display belong in one helper. Any inline * 100 or number_format scattered through views will eventually disagree with the pricing helper. The v1.0.2 multiplication fix is the exact class of bug this causes.

Pin the kit version you installed. Record it in the scaffold commit message and in a KIT.md at the repo root: kit name, version, install date, what you changed, what you deleted. Six months from now, that file is the difference between a two-hour upgrade and a two-day archaeology exercise.

Assume bus factor one and plan accordingly. Single-author releases, small registry, no benchmarks for scale or compliance. None of that blocks a pilot; all of it argues against making this an automatic platform standard. Validate install friction, customization effort, and upgrade cost in a non-critical project first — and if the answer to "can we rebuild this storefront on a different frontend without discarding domain logic?" is no, you've built the lock-in yourself.