
Prerequisites
| Requirement | Version |
|---|---|
| PHP | 8.4+ |
| Laravel | 12.0+ |
| Shopper | 2.7+ |
| Node.js | 20+ |
Installation
Theshopper:kit:install command is built into Shopper. No additional package is required.
| Package | Version | Purpose |
|---|---|---|
livewire/livewire | ^3.7 | Reactive server-driven components |
livewire/flux | ^2.0 | UI component library (buttons, inputs, modals, cards) |
livewire/volt | ^1.7 | Single-file Livewire components |
laravel/fortify | ^1.25 | Authentication backend (login, register, 2FA) |
shopper/stripe | ^2.7 | Stripe payment integration |
composer.json. The code is yours.
Project Structure
The starter kit publishes files into standard Laravel directories. Here is the full structure.Routing
The starter kit defines all storefront routes inroutes/web.php. Each page is a full-page Livewire component.
Public Routes
| Route | Component | Description |
|---|---|---|
/ | Home | Homepage with featured collections, products, and categories |
/shop | ProductIndex | Product catalog with search and filtering |
/shop/{product:slug} | ProductShow | Product detail with variant selection |
/categories | CategoryIndex | All categories |
/categories/{category:slug} | CategoryShow | Products in a category |
/collections/{collection:slug} | CollectionShow | Products in a collection |
/search | SearchProducts | Full-text search across products |
/cart | Cart | Shopping cart |
Authenticated Routes
These routes require the user to be logged in and have a verified email.| Route | Component | Description |
|---|---|---|
/checkout | Checkout | Multi-step checkout flow |
/checkout/payment/{number} | StripePayment | Stripe Payment Element |
/checkout/success/{order} | Volt page | Order confirmation |
/account/orders | Volt page | Order history |
/account/orders/{order} | Volt page | Order detail |
/account/addresses | Addresses | Address management |
/profile/edit | Volt page | Profile settings |
/profile/appearance | Volt page | Dark mode / appearance |
/profile/security | Volt page | Password and two-factor authentication |
/webhooks/stripe with rate limiting.
Architecture
The starter kit follows a clear separation of concerns. Business logic lives in Action classes, data structures in DTOs, and UI in Livewire components. This makes it straightforward to modify any part of the storefront without affecting others.Actions
Actions are single-responsibility classes that encapsulate business logic. They are resolved from the container, so you can swap implementations or add dependencies as needed.| Action | Responsibility |
|---|---|
BuildShippingPackages | Builds package dimensions from cart items for carrier rate requests |
FetchDeliveryRates | Queries available carriers and returns shipping rate options |
FetchPaymentMethods | Loads payment methods available for the customer’s country |
ResolveZoneForCountry | Resolves the pricing zone for a given country with caching |
DTOs
Data Transfer Objects provide type-safe structures for data passed between components.| DTO | Purpose |
|---|---|
AddressData | Structured address data for forms and checkout |
CountryByZoneData | Zone session data (zone ID, country code, currency code) |
PriceData | Formatted price with amount, currency, and comparison price |
ProductReviewsData | Aggregated review data (average rating, count, distribution) |
Models
The starter kit publishes model files that extend Shopper’s base models. These are configured inconfig/shopper/models.php so that Shopper’s internals use your extended versions.
CheckoutSession
TheCheckoutSession class defines constants for session keys used throughout the checkout flow. This provides a single place to reference all checkout-related session data.
Helpers
Theapp/helpers.php file defines three global functions used across the storefront.
| Function | Purpose |
|---|---|
cartSession() | Returns the current cart or creates a new one with the active zone, currency, and channel |
current_currency() | Returns the currency code for the selected zone, or the store default |
current_tax_label() | Returns the tax label (“TTC” or “HT”) based on the zone’s tax configuration |
Checkout Flow
The checkout is a multi-step process handled by theCheckout Livewire component. Each step validates its data before proceeding to the next.
Step 1 - Shipping Address. The customer enters a new address or selects one of their saved addresses. The address is stored in the session and attached to the cart via CartManager::addAddress().
Step 2 - Delivery Options. The BuildShippingPackages action builds package data from the cart, then FetchDeliveryRates queries configured carriers for available shipping rates based on the address and packages. The customer selects a delivery option.
Step 3 - Payment. FetchPaymentMethods loads available payment methods for the customer’s country. When the customer places the order, the CreateOrder action converts the cart into an order inside a database transaction, adds shipping costs, and initiates payment processing through Shopper’s PaymentProcessingService.
For Stripe payments, the customer is redirected to a dedicated payment page (StripePayment) that renders the Stripe Payment Element. The StripeWebhookController handles payment confirmation webhooks.
Zones and Currency
The starter kit uses Shopper’s zone system for multi-currency and regional pricing. TheZoneSelector component in the footer lets customers pick their country. When a zone is selected, the ZoneSessionManager stores a CountryByZoneData DTO in the session with the zone ID, country code, and currency code. All prices across the storefront update to reflect the zone’s currency.
If no zone is selected, the storefront falls back to your store’s default currency from config('shopper.core.currency').
The current_tax_label() helper checks the zone’s tax configuration to display “TTC” (tax-inclusive) or “HT” (tax-exclusive) labels alongside prices.
To enable zone selection, create at least one active zone in your Shopper admin panel. You can optionally set a default zone using the SHOPPER_DEFAULT_ZONE environment variable.
Customization
Once installed, every file belongs to your project. Here are the most common customization paths.Styling
All views use Flux UI components and Tailwind CSS v4. Modify colors, spacing, and layouts by editing the Blade templates inresources/views/. The base layout is in resources/views/layouts/store.blade.php.
Homepage Sections
The homepage is composed of three independent Livewire components, each with its own view.| Component | View | What it shows |
|---|---|---|
FeaturedCollections | pages/home/featured-collections.blade.php | Manual collections |
FeaturedProducts | pages/home/featured-products.blade.php | Latest published products |
ShopByCategory | pages/home/shop-by-category.blade.php | Root categories |
resources/views/pages/home.blade.php to change the homepage layout.
Checkout
To modify the checkout flow, edit the action classes inapp/Actions/Checkout/. Each action handles one concern, so you can change how shipping rates are calculated without touching payment logic.
To add a new payment provider, implement the provider using Shopper’s payment system and register it in your admin panel. The checkout will automatically pick it up through FetchPaymentMethods.
Adding Pages
Create a new Livewire component and register a route inroutes/web.php. Follow the existing pattern of full-page components in app/Livewire/Pages/.
Models
Add methods, scopes, or relationships directly to the model files inapp/Models/. These models extend Shopper’s base models, so all existing functionality is preserved.