Skip to content

Vue Starter Kit

A Shopper storefront built with Inertia, Vue 3, shadcn-vue and Tailwind CSS v4.

The Vue Starter Kit is a storefront for Shopper built with Inertia.js and Vue 3. Laravel controllers query the Shopper models and pass the data to Vue pages as Inertia props, so there is no separate API layer to maintain, and Inertia navigates between pages without full reloads. The interface uses shadcn-vue components and Tailwind CSS v4, and Laravel Wayfinder and a PHP-to-TypeScript transformer give the pages typed routes and typed data.

Vue Starter Kit storefront

Prerequisites

RequirementVersion
PHP8.4+
Laravel12.0+
Shopper2.11+
Node.js20.19+ or 22.12+

Installation

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

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

The installer downloads the kit, reads its manifest and copies the storefront files into your project, asking before it overwrites each file your application already has. It then installs the following dependencies.

PackagePurpose
inertiajs/inertia-laravelInertia server-side adapter for Laravel
laravel/fortifyAuthentication backend (login, register, 2FA)
laravel/wayfinderTyped route helpers generated from your routes
spatie/laravel-typescript-transformerGenerates TypeScript types from PHP DTOs and enums
shopper/stripeStripe payment integration

It also installs laravel/boost and laravel/pao as development dependencies.

After installing dependencies, the kit runs its post-install commands once you confirm them: php artisan migrate, php artisan storage:link, npm install and npm run build.

The installer then writes a .shopper-kit file that lists every copied file and removes the kit package from your composer.json. Every file it copied belongs to your project.

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/vue-starter-kit

Project Structure

The starter kit publishes files into standard Laravel directories. The backend is shared with the React Starter Kit; only the resources/js frontend differs. Here is the structure it adds to your project.

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/
│   ├── InteractsWithStorefrontMedia.php
│   ├── PasswordValidationRules.php
│   └── ProfileValidationRules.php
├── DTO/
│   ├── AddressData.php
│   ├── CountryByZoneData.php
│   ├── PriceData.php
│   └── ProductReviewsData.php
├── Http/
│   ├── Controllers/
│   │   ├── Account/        # Address and order management
│   │   ├── Settings/       # Profile and security
│   │   ├── Shop/           # Home, products, cart, checkout, zone
│   │   └── StripeWebhookController.php
│   ├── Middleware/
│   │   ├── HandleAppearance.php
│   │   └── HandleInertiaRequests.php
│   └── Requests/Settings/  # Profile and password form requests
├── Models/
│   ├── Category.php
│   ├── Channel.php
│   ├── Collection.php
│   ├── Product.php
│   ├── ProductVariant.php
│   └── User.php
├── Providers/
│   ├── AppServiceProvider.php
│   ├── FortifyServiceProvider.php
│   └── TypeScriptTransformerServiceProvider.php
├── Traits/
│   └── HasProductPricing.php
├── CheckoutSession.php
└── helpers.php

resources/js/
├── components/
│   ├── account/       # Order status badge
│   ├── shop/          # Product cards, price display, zone selector, Stripe form
│   └── ui/            # shadcn-vue primitives (button, dialog, select, ...)
├── composables/       # useCart, useShop, useStripeElements, useAppearance
├── layouts/           # Storefront, account, settings, and auth layouts
├── lib/               # format, stripe, and utility helpers
├── pages/
│   ├── account/       # Orders, order detail, addresses
│   ├── auth/          # Login, register, password reset, 2FA
│   ├── settings/      # Profile, appearance, security
│   ├── shop/          # Home, catalog, product, cart, checkout
│   └── dashboard.vue  # Customer dashboard
├── types/             # Shared and generated TypeScript types
└── app.ts             # Inertia application entry point

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

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

Routing

The starter kit defines all storefront routes in routes/web.php. Unlike the Livewire kit, each page is rendered by a dedicated controller that returns an Inertia response. Routes are named so you can reference them through Wayfinder in your Vue components.

Public Routes

RouteControllerDescription
GET /Shop\HomeControllerHomepage with featured collections, products, and categories
GET /shopShop\ProductController@indexProduct catalog with search and filtering
GET /shop/{product:slug}Shop\ProductController@showProduct detail with variant selection
GET /categoriesShop\CategoryController@indexAll categories
GET /categories/{category:slug}Shop\CategoryController@showProducts in a category
GET /collections/{collection:slug}Shop\CollectionController@showProducts in a collection
GET /searchShop\SearchControllerSearch products by name
GET /cartShop\CartController@indexShopping cart

Cart mutations are exposed as their own endpoints, limited to 60 requests per minute: POST /cart adds a line, PATCH /cart/{line} updates a quantity, DELETE /cart/{line} removes a line, and DELETE /cart clears the cart. The active pricing zone is changed with PATCH /zone. Search and the zone change are limited to 30 requests per minute.

Authenticated Routes

These routes require the user to be logged in. They also carry Laravel's verified middleware, which only checks the email address when the User model implements MustVerifyEmail. The kit's model does not, so a customer can check out right after registering. The profile settings page requires the login only.

RouteControllerDescription
GET /checkoutShop\CheckoutController@indexMulti-step checkout flow
GET /checkout/stripe-returnShop\CheckoutController@stripeReturnReturn URL of a Stripe payment, creates the order
GET /checkout/payment/{number}Shop\StripePaymentControllerStripe Payment Element for an existing order. The checkout does not link to it, it renders the Payment Element in its payment step
GET /checkout/success/{order}Shop\CheckoutSuccessControllerOrder confirmation
GET /dashboardInertia pageCustomer dashboard
GET /account/ordersAccount\OrderController@indexOrder history
GET /account/orders/{order}Account\OrderController@showOrder detail
GET /account/addressesAccount\AddressController@indexAddress management
GET /settings/profileSettings\ProfileController@editProfile settings
GET /settings/appearanceInertia pageLight and dark appearance
GET /settings/securitySettings\SecurityController@editPassword and two-factor authentication

The checkout flow posts to dedicated endpoints for each step (checkout/shipping-address, checkout/shipping-option, checkout/prepare-payment, checkout/place-order). The Stripe webhook endpoint is POST /webhooks/stripe, outside the authenticated group and limited to 60 requests per minute. bootstrap/app.php excludes webhooks/* from CSRF verification so Stripe can reach it.

Architecture

Business logic lives in Action classes, data structures in DTOs, HTTP handling in controllers, and UI in Vue components, so you can change one layer of the storefront without editing the 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

Order creation is wrapped in CreateOrder. It answers 422 when the checkout session has no delivery option or payment method, and 403 when the cart belongs to another customer. It then takes a 10-second Cache::lock on the cart, so a second submit of the same cart gets a 409 instead of a duplicate order, and converts the cart inside a database transaction.

DTOs

Data Transfer Objects give a fixed shape to the data passed between the backend and the Vue frontend. Because the kit uses the TypeScript Transformer, these DTOs also become TypeScript types your components can import.

DTOPurpose
AddressDataStructured address data for forms and checkout
CountryByZoneDataSelected zone and country (zone ID, code and name, country ID, name, code and flag, currency code)
PriceDataPrice with its comparison price and discount percentage
ProductReviewsDataProduct reviews with the average rating and the review count

Controllers

Each storefront page is rendered by a controller in app/Http/Controllers/. Controllers query Shopper's models, eager load what the page displays, and return an Inertia response that renders the matching page component. The product page answers 404 for an unpublished product and loads prices in the active currency only.

app/Http/Controllers/Shop/ProductController.php
public function show(Product $product): Response
{
    abort_unless($product->isPublished(), 404);

    $currencyCode = current_currency();
    $priceConstraint = fn ($q) => $q->whereRelation('currency', 'code', $currencyCode);

    $product->load([
        'brand',
        'media',
        'prices' => $priceConstraint,
        'relatedProducts.brand',
        'relatedProducts.media',
        'relatedProducts.prices' => $priceConstraint,
        'variants.media',
        'variants.values.attribute',
        'variants.prices' => $priceConstraint,
    ]);

    // ...

    return Inertia::render('shop/product', [
        'product' => $product,
        'variantOptions' => $variantOptions,
    ]);
}

To change what a page receives, edit its controller. To change how it looks, edit the matching page component in resources/js/pages/.

Inertia Shared Data

The HandleInertiaRequests middleware shares data with every page, so your components receive the authenticated user and the current shop state without another request. The shop prop is built by shopProps().

app/Http/Middleware/HandleInertiaRequests.php
return [
    'cart_count' => $cart?->lines->sum('quantity') ?? 0,
    'zone' => $zone ? [
        'country_code' => $zone->countryCode,
        'country_name' => $zone->countryName,
        'currency_code' => $zone->currencyCode,
        'zone_id' => $zone->zoneId,
    ] : null,
    'currency' => current_currency(),
    'channels' => Channel::query()
        ->scopes('enabled')
        ->select('id', 'name', 'slug')
        ->get()
        ->toArray(),
    'available_zones' => fn (): array => resolve(GetCountriesByZone::class)->handle()->values()->toArray(),
    'tax_label' => current_tax_label(),
    'nav_categories' => $this->topCategories(4, 'nav'),
    'footer_categories' => $this->topCategories(6, 'footer'),
];

On the frontend, the useShop composable reads this shared data and changes the country with changeZone(). The useCart composable exposes add, update, remove and clear, which call the cart endpoints.

Models

The starter kit adds Category, Channel, Collection, Product and ProductVariant models in app/Models/ that extend Shopper's base models. They are registered in config/shopper/models.php, so Shopper's internals and the admin panel use your versions.

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

use App\Concerns\InteractsWithStorefrontMedia;
use App\Traits\HasProductPricing;
use Illuminate\Database\Eloquent\Attributes\Scope;
use Illuminate\Database\Eloquent\Builder;
use Shopper\Models\Product as Model;

final class Product extends Model
{
    use HasProductPricing;
    use InteractsWithStorefrontMedia;

    /** @param  Builder<self>  $query */
    #[Scope]
    protected function withCurrentPrices(Builder $query): Builder
    {
        return $query->with([
            'prices' => fn ($q) => $q->whereRelation('currency', 'code', current_currency()),
        ]);
    }
}

You can add custom logic directly to these models. Any method you add is available throughout the storefront and in Shopper's admin panel. The withCurrentPrices scope loads only the prices in the active currency, and HasProductPricing adds getFormattedPrice(), which returns a PriceData with the amount, the comparison price and the discount percentage in that currency. The InteractsWithStorefrontMedia trait appends thumbnail and images attributes to every JSON response, so your Vue components receive media URLs they can use as is.

CheckoutSession

The CheckoutSession class defines the session keys of the checkout in one place. The checkout stores the shipping address, the delivery option and the payment method under these keys. BILLING_ADDRESS and SAME_AS_SHIPPING are defined, but the kit's checkout does not use them.

use App\CheckoutSession;

session()->get(CheckoutSession::KEY);              // 'checkout'
session()->get(CheckoutSession::SHIPPING_ADDRESS); // 'checkout.shipping_address'
session()->get(CheckoutSession::BILLING_ADDRESS);  // 'checkout.billing_address'
session()->get(CheckoutSession::SAME_AS_SHIPPING); // 'checkout.same_as_shipping'
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 from shopper_currency()
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

Type Safety

Three tools give your Vue components the shape of the backend data, so a renamed route or a changed DTO shows up as a TypeScript error.

ToolWhat it provides
WayfinderTyped route helpers generated from your routes into resources/js/routes and resources/js/actions, so shop.product.url({ product: product.slug }) builds a product URL
TypeScript TransformerGenerates TypeScript definitions from your PHP DTOs and enums into resources/js/types/generated.d.ts
@shopperlabs/shopper-typesShared domain types (Address, Cart, Order, Product, and enums) published as an npm package

The Wayfinder Vite plugin in vite.config.ts regenerates the route helpers while npm run dev runs and during npm run build. The TypeScriptTransformerServiceProvider registers the transformer; run it after changing a DTO to refresh the types your components import.

php artisan typescript:transform

Checkout Flow

The checkout is a multi-step process handled by CheckoutController. Each step posts to its own endpoint and 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 to fill the form. The address takes the country selected in the storefront, then it is stored in the session and attached to the cart as its shipping address through 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 the enabled payment methods of the zone that contains the address country, and keeps only those whose driver is configured: Stripe is listed once STRIPE_SECRET_KEY is set in your .env. For a method other than Stripe, such as cash on delivery, placing the order runs the CreateOrder action, which converts the cart into an order inside a database transaction and adds shipping costs, then initiates payment processing through Shopper's PaymentProcessingService.

For Stripe payments, choosing the method creates a Stripe PaymentIntent without creating an order, and the payment step renders the Stripe Payment Element through the useStripeElements composable. Once Stripe confirms the payment, it sends the customer back to /checkout/stripe-return, which checks the PaymentIntent and runs CreateOrder.

The StripeWebhookController receives Stripe events on /webhooks/stripe, finds the order through its payment transaction, and reports an authorization or a capture whose amount in cents differs from the order's price_amount without changing the order. An authorized payment sets the order's payment status to Authorized and a captured one to Paid. A failed or canceled payment cancels the order and voids its payment, and a refund cancels the order with the Refunded payment status.

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 the country code in the session and resolves it to a CountryByZoneData DTO with the zone ID, country code, and currency code. It also resets the checkout in progress and moves the cart to the new zone and currency. Product prices across the storefront switch to the zone's currency through the shared shop prop.

If no zone is selected, the storefront falls back to your store's default currency from 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.

Customization

Once installed, every file belongs to your project. These are the places you change first.

Styling

All views use shadcn-vue components and Tailwind CSS v4. Modify colors, spacing, and layouts by editing the components in resources/js. UI primitives live in resources/js/components/ui/, and the storefront header and footer are in resources/js/layouts/storefront/.

Pages

Each page is a Vue single-file component in resources/js/pages/. Edit any .vue file to change a page's layout or content. To change the data a page receives, edit its controller in app/Http/Controllers/.

Pages do not declare their layout: the layout callback of resources/js/app.ts picks it from the page name.

Page nameLayout
shop/*Storefront header and footer, from layouts/storefront-layout.vue
account/* and dashboardStorefront layout with the account navigation of layouts/account-layout.vue
settings/*Account layout with the settings navigation of layouts/settings-sub-layout.vue
auth/*Authentication layout, from layouts/auth-layout.vue
Any other nameSidebar application layout, from layouts/app-layout.vue

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, register it in your admin panel, and enable it on the zones where customers can use it. FetchPaymentMethods lists it once its driver is configured, and placing the order follows the redirect URL the driver returns, if any.

Adding Pages

Create a controller, register a named route in routes/web.php, and add the matching Vue component under resources/js/pages/. Name the page under shop/ so it renders with the storefront header and footer.

app/Http/Controllers/AboutController.php
namespace App\Http\Controllers;

use Inertia\Inertia;
use Inertia\Response;

final class AboutController extends Controller
{
    public function __invoke(): Response
    {
        return Inertia::render('shop/about');
    }
}
routes/web.php
use App\Http\Controllers\AboutController;

Route::get('about', AboutController::class)->name('about');
resources/js/pages/shop/about.vue
<script setup lang="ts">
import { Head } from '@inertiajs/vue3';
import Container from '@/components/shop/container.vue';
</script>

<template>
    <Head title="About Us" />

    <Container class="py-8 sm:py-12">
        <h1>About Us</h1>
    </Container>
</template>

Wayfinder adds an about function to @/routes the next time Vite runs, so a link in the footer reads <Link :href="about.url()">About</Link>, the way resources/js/layouts/storefront/store-footer.vue links to home.

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
use Illuminate\Database\Eloquent\Attributes\Scope;
use Illuminate\Database\Eloquent\Builder;

final class Product extends Model
{
    #[Scope]
    protected function featured(Builder $query): Builder
    {
        return $query->where('featured', true);
    }
}

Last updated on

Edit on GitHub