Skip to content

Livewire Starter Kit

A complete storefront built with Livewire 3, Flux UI and Tailwind CSS v4.

The Livewire Starter Kit is a complete storefront for Shopper, built entirely within the Laravel ecosystem. It uses Livewire 3 for reactive components, Flux UI for the design system, and Tailwind CSS v4 for styling. Because Shopper's admin panel is also built with Livewire, you can reuse patterns and components across your admin and storefront.

Livewire Starter Kit storefront

Prerequisites

The installer checks the PHP, Laravel and Shopper versions of the kit's manifest before it copies anything.

RequirementVersion
PHP8.4+
Laravel11.48+
Shopper2.11.1+
Node.js20+

Installation

The shopper:kit:install command is built into Shopper. No additional package is required.

php artisan shopper:kit:install shopperlabs/livewire-starter-kit

The installer downloads the kit, reads its manifest, copies all storefront files into your project, and installs the following dependencies.

PackagePurpose
livewire/fluxUI component library (buttons, inputs, modals, cards)
livewire/voltSingle-file Livewire components
laravel/fortifyAuthentication backend (login, register, 2FA)
shopper/stripeStripe payment integration
laravel/boostDevelopment dependency for AI-assisted development

After installing dependencies, the kit runs its post-install commands: php artisan migrate and php artisan storage:link.

Once complete, the kit package is removed from your composer.json. The code is yours.

The post-install commands do not build the frontend assets. Install the npm packages and build them once the installer finishes:

npm install
npm run build

On an existing project, create a new branch before installing so you can review every change.

git checkout -b storefront
php artisan shopper:kit:install shopperlabs/livewire-starter-kit

Project Structure

The starter kit publishes files into standard Laravel directories. Here is the full structure.

app/
├── Actions/
│   ├── Cart/
│   │   └── AddToCart.php
│   ├── Checkout/
│   │   ├── BuildShippingPackages.php
│   │   ├── FetchDeliveryRates.php
│   │   ├── FetchPaymentMethods.php
│   │   └── ResolveZoneForCountry.php
│   ├── Fortify/
│   │   ├── CreateNewUser.php
│   │   └── ResetUserPassword.php
│   ├── Product/
│   │   ├── AddProductReviewAction.php
│   │   ├── BuildVariantOptions.php
│   │   └── ResolveVariantAvailability.php
│   ├── CreateOrder.php
│   ├── GetCountriesByZone.php
│   └── ZoneSessionManager.php
├── Concerns/
│   ├── PasswordValidationRules.php
│   └── ProfileValidationRules.php
├── DTO/
│   ├── AddressData.php
│   ├── CountryByZoneData.php
│   ├── PriceData.php
│   └── ProductReviewsData.php
├── Http/Controllers/
│   ├── StripeReturnController.php
│   └── StripeWebhookController.php
├── Livewire/
│   ├── Account/
│   │   ├── AddressForm.php
│   │   └── Addresses.php
│   ├── Actions/
│   │   └── Logout.php
│   ├── Home/
│   │   ├── FeaturedCollections.php
│   │   ├── FeaturedProducts.php
│   │   └── ShopByCategory.php
│   ├── Pages/
│   │   ├── Cart.php
│   │   ├── CategoryIndex.php
│   │   ├── CategoryShow.php
│   │   ├── Checkout.php
│   │   ├── CollectionShow.php
│   │   ├── Home.php
│   │   ├── ProductIndex.php
│   │   ├── ProductShow.php
│   │   ├── SearchProducts.php
│   │   └── StripePayment.php
│   ├── CartCount.php
│   ├── StoreFooter.php
│   ├── StoreHeader.php
│   └── ZoneSelector.php
├── Models/
│   ├── Category.php
│   ├── Channel.php
│   ├── Product.php
│   ├── ProductVariant.php
│   └── User.php
├── Providers/
│   ├── AppServiceProvider.php
│   ├── FortifyServiceProvider.php
│   └── VoltServiceProvider.php
├── Traits/
│   └── HasProductPricing.php
├── CheckoutSession.php
└── helpers.php

resources/views/
├── components/        # Blade components (product cards, price display, badges)
├── layouts/           # Store, account, and auth layouts
├── livewire/          # Livewire component views (header, footer, cart count)
├── pages/
│   ├── auth/          # Login, register, password reset, 2FA
│   ├── home/          # Homepage sections (collections, products, categories)
│   ├── settings/      # Profile, appearance, security
│   ├── shop/          # Product listing, detail, cart, checkout
│   └── account/       # Order history, order detail
└── partials/          # Shared head, settings heading

routes/
├── web.php            # Storefront, checkout, account routes
└── settings.php       # Profile and security routes

tests/
├── Feature/Auth/      # Authentication tests
└── Feature/Settings/  # Profile and security tests

Routing

The starter kit defines all storefront routes in routes/web.php. Each page is a full-page Livewire component.

Public Routes

These routes are open to guests.

RouteComponentDescription
/HomeHomepage with featured collections, products, and categories
/shopProductIndexProduct catalog with search and filtering
/shop/{product:slug}ProductShowProduct detail with variant selection
/categoriesCategoryIndexAll categories
/categories/{category:slug}CategoryShowProducts in a category
/collections/{collection:slug}CollectionShowProducts in a collection
/searchSearchProductsFull-text search across products
/cartCartShopping cart

Authenticated Routes

These routes require the user to be logged in and have a verified email. The /profile/edit route only requires the user to be logged in.

RouteComponentDescription
/checkoutCheckoutMulti-step checkout flow
/checkout/paymentStripePaymentStripe Payment Element
/checkout/payment/returnStripeReturnControllerCreates the order once Stripe confirms the payment
/checkout/success/{order}Volt pageOrder confirmation
/dashboardBlade viewCustomer dashboard with links to orders and addresses
/account/ordersVolt pageOrder history
/account/orders/{order}Volt pageOrder detail
/account/addressesAddressesAddress management
/profile/editVolt pageProfile settings
/profile/appearanceVolt pageDark mode / appearance
/profile/securityVolt pagePassword and two-factor authentication

The Stripe webhook endpoint is registered at /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.

use App\Actions\Cart\AddToCart;
use App\Actions\Checkout\FetchDeliveryRates;
use App\Actions\CreateOrder;

resolve(AddToCart::class)->handle($product, $selectedVariant);
resolve(FetchDeliveryRates::class)->handle($addressData, $packages);
resolve(CreateOrder::class)->handle();

The checkout flow is split into four focused actions.

ActionResponsibility
BuildShippingPackagesBuilds package dimensions from cart items for carrier rate requests
FetchDeliveryRatesQueries available carriers and returns shipping rate options
FetchPaymentMethodsLoads payment methods available for the customer's country
ResolveZoneForCountryResolves the pricing zone for a given country with caching

DTOs

Data Transfer Objects provide type-safe structures for data passed between components.

DTOPurpose
AddressDataStructured address data for forms and checkout
CountryByZoneDataZone session data (zone ID, country code, currency code)
PriceDataFormatted price with amount, currency, and comparison price
ProductReviewsDataAggregated review data (reviews, average rating, total count)

Models

The starter kit publishes model files that extend Shopper's base models. These are configured in config/shopper/models.php so that Shopper's internals use your extended versions.

app/Models/Product.php
namespace App\Models;

use App\Traits\HasProductPricing;
use Shopper\Models\Product as Model;

final class Product extends Model
{
    use HasProductPricing;
}

You can add custom logic directly to these models. Any method you add is available throughout the storefront and in Shopper's admin panel.

CheckoutSession

The CheckoutSession class defines constants for session keys used throughout the checkout flow. This provides a single place to reference all checkout-related session data.

use App\CheckoutSession;

session()->get(CheckoutSession::KEY);              // 'checkout'
session()->get(CheckoutSession::SHIPPING_ADDRESS);  // 'checkout.shipping_address'
session()->get(CheckoutSession::SHIPPING_OPTION);   // 'checkout.shipping_option'
session()->get(CheckoutSession::PAYMENT);           // 'checkout.payment'

Helpers

The app/helpers.php file defines three global functions used across the storefront.

FunctionPurpose
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") from the tax zone of the selected country, or an empty string when no zone is selected

Checkout Flow

The checkout is a multi-step process handled by the Checkout 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 with a manual payment method, 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 order does not exist yet when the customer leaves the checkout. The checkout creates a Stripe PaymentIntent for the cart total plus shipping and redirects to a dedicated payment page (StripePayment) that renders the Stripe Payment Element. Once Stripe confirms the payment, the StripeReturnController checks the PaymentIntent status, creates the order with the CreateOrder action, and redirects to the confirmation page. The StripeWebhookController then updates the order's payment status from Stripe events.

Zones and Currency

The starter kit uses Shopper's zone system for multi-currency and regional pricing. The ZoneSelector 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 the default currency set in your store settings, returned by shopper_currency().

The current_tax_label() helper reads the tax zone of the selected country 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. When your zones cover a single country, the ZoneSelector selects it automatically on the first visit.

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 in resources/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.

ComponentViewWhat it shows
FeaturedCollectionspages/home/featured-collections.blade.phpThe three collections with the most products
FeaturedProductspages/home/featured-products.blade.phpUp to eight published products marked as featured
ShopByCategorypages/home/shop-by-category.blade.phpRoot categories

Remove or reorder these components in resources/views/pages/home.blade.php to change the homepage layout.

Checkout

To modify the checkout flow, edit the action classes in app/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 in routes/web.php. Follow the existing pattern of full-page components in app/Livewire/Pages/.

app/Livewire/Pages/About.php
namespace App\Livewire\Pages;

use Illuminate\Contracts\View\View;
use Livewire\Component;

class About extends Component
{
    public function render(): View
    {
        return view('pages.about')
            ->title('About Us');
    }
}
routes/web.php
use App\Livewire\Pages\About;

Route::get('about', About::class)->name('about');

Models

Add methods, scopes, or relationships directly to the model files in app/Models/. These models extend Shopper's base models, so all existing functionality is preserved.

app/Models/Product.php
namespace App\Models;

use Illuminate\Database\Eloquent\Builder;
use Shopper\Models\Product as Model;

final class Product extends Model
{
    public function scopeFeatured(Builder $query): Builder
    {
        return $query->where('featured', true);
    }
}

Last updated on

Edit on GitHub