Skip to content

Vue Starter Kit

A Shopper storefront built with Inertia, Vue 3, shadcn-vue and Tailwind CSS v4, installed into your Laravel application with one command.

The Vue Starter Kit is a storefront for Shopper built with Inertia and Vue 3. Laravel controllers query the Shopper models and pass the data to Vue pages as Inertia props, so the kit does not go through the Store API and there is no separate API layer to maintain. 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.

The kit is installed once, with the starter kit installer. Every file it copies belongs to your project afterwards.

Prerequisites

The installer checks the PHP, Laravel and Shopper versions of the kit's manifest before it copies anything, and the kit's Vite version needs the Node.js versions below. Shopper must already be installed in the application.

RequirementVersion
PHP8.3+
Laravel12.68+ or 13.27+
Shopper3.0+
Node.js20.19+ or 22.12+

Installation

Run the installer in a Laravel application where Shopper is installed, with the package name of the kit. Installing a Starter Kit lists the steps from a new Laravel application.

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. On a new Laravel application, the kit replaces 14 files of the skeleton, such as routes/web.php, bootstrap/app.php, app/Models/User.php, package.json, resources/css/app.css and config/shopper/models.php, and the installer asks before overwriting each of them. It then installs these Composer packages:

PackagePurpose
inertiajs/inertia-laravelInertia server-side adapter for Laravel
laravel/fortifyAuthentication backend (login, register, password reset, two-factor authentication)
laravel/wayfinderTyped route functions generated from your routes
spatie/laravel-typescript-transformerTypeScript types generated from the PHP DTOs
shopper/stripeStripe payment driver

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

Once you confirm them, the installer runs the kit's post-install commands: php artisan migrate, php artisan storage:link, npm install and npm run build. It then writes a .shopper-kit file that lists every copied file and removes the kit package from your composer.json.

First Run

Start the development server from the root of your project:

php artisan serve

The home page, the catalog, the categories, the search, the cart and the login and register pages answer at http://localhost:8000. The checkout, account and settings pages send guests to the login page.

The post-install commands built the assets once. While you work on the Vue pages, run Vite in a second terminal, so the browser reloads each change and Wayfinder regenerates the route functions when you add a route:

npm run dev

Run npm run build again before you deploy.

Store Data

A new store has no products, so every listing renders empty until you add a catalog. Sign in to the admin panel, complete the setup wizard, then create the data a purchase goes through:

  1. A zone with the countries you sell to and their currency, such as a North America zone with the United States and Canada in USD. Enable a payment method on it, such as the cash on delivery method that Shopper seeds, and a carrier with at least one shipping option, such as "Standard shipping" at 500 cents.
  2. A category for the storefront navigation.
  3. A product that is published, with a price in the zone's currency and stock in an inventory location. A canvas tote bag at 2500 cents ($25.00) works. Mark it as featured to show it on the home page.

With this data, a customer picks the United States in the country dialog that opens on their first visit, adds two tote bags to the cart, registers, and checks out with cash on delivery: the two bags and the standard shipping make an order of 5500 cents.

Stripe

The installer added the shopper/stripe package, and the payment step of the kit's checkout renders the Stripe Payment Element. Add the keys of your Stripe account to .env, using the test keys while you build the store:

.env
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Until the secret key and the webhook secret are set, the checkout does not list the payment methods that use Stripe. Manual methods, such as cash on delivery, work without any key. The payment step reads the publishable key to load the Payment Element. Configuration describes each variable, and Payment Method Setup shows how to create a Stripe payment method and enable it on your zones.

Project Structure

The starter kit publishes files into standard Laravel directories. Here is the structure it adds to your project.

app/
├── Actions/
│   ├── Cart/
│   │   └── AddToCart.php
│   ├── Checkout/
│   │   ├── BuildShippingPackages.php
│   │   ├── CompleteCheckout.php
│   │   ├── CreatePaymentSession.php
│   │   ├── FetchDeliveryRates.php
│   │   └── FetchPaymentMethods.php
│   ├── Fortify/
│   │   ├── CreateNewUser.php
│   │   └── ResetUserPassword.php
│   ├── Product/
│   │   ├── BuildVariantOptions.php
│   │   └── ResolveVariantAvailability.php
│   ├── GetCountriesByZone.php
│   └── ZoneSessionManager.php
├── Concerns/
│   ├── InteractsWithStorefrontMedia.php
│   ├── PasswordValidationRules.php
│   └── ProfileValidationRules.php
├── DTO/
│   ├── AddressData.php
│   ├── CountryByZoneData.php
│   ├── PriceData.php
│   └── ProductReviewsData.php
├── Exceptions/
│   └── CheckoutException.php
├── Http/
│   ├── Controllers/
│   │   ├── Account/
│   │   ├── Settings/
│   │   ├── Shop/
│   │   ├── PaymentWebhookController.php
│   │   └── StripeReturnController.php
│   ├── Middleware/
│   │   ├── HandleAppearance.php
│   │   └── HandleInertiaRequests.php
│   └── Requests/Settings/
├── Models/
│   ├── Category.php
│   ├── Channel.php
│   ├── Collection.php
│   ├── Product.php
│   ├── ProductVariant.php
│   └── User.php
├── Providers/
│   ├── AppServiceProvider.php
│   ├── FortifyServiceProvider.php
│   └── TypeScriptTransformerServiceProvider.php
├── Traits/
│   └── HasProductPricing.php
└── helpers.php

resources/js/
├── components/
│   ├── account/
│   ├── shop/
│   └── ui/
├── composables/
├── layouts/
├── lib/
├── pages/
│   ├── account/
│   ├── auth/
│   ├── settings/
│   ├── shop/
│   └── dashboard.vue
├── types/
└── app.ts

routes/
├── settings.php
├── web.php
└── webhooks.php

tests/
├── Feature/Auth/
├── Feature/Settings/
├── Feature/Shop/
└── Unit/

The Account, Settings and Shop controllers render the matching folders of resources/js/pages. The components/shop folder holds the product cards, the price display, the zone selector and the Stripe form, and components/ui the shadcn-vue primitives. The composables folder holds useCart, useShop, useStripeElements and useAppearance, among others.

Routing

The starter kit defines the storefront routes in routes/web.php, the account settings routes in routes/settings.php and the payment webhook route in routes/webhooks.php. Each page is rendered by a controller that returns an Inertia response, and every route is named so your Vue components can call it through Wayfinder.

Public Routes

These routes are open to guests.

RouteControllerDescription
GET /Shop\HomeControllerHomepage with featured collections, products, and categories
GET /shopShop\ProductController@indexProduct catalog with search, a category filter and sorting
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, from 2 characters
GET /cartShop\CartController@indexShopping cart

Cart mutations have 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. POST /cart/coupon applies a discount code, with at most 5 attempts per minute for each customer, and DELETE /cart/coupon/{code} removes it. PATCH /zone changes the country of the visitor, and GET /search answers 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-returnStripeReturnControllerReturn URL of a Stripe payment, creates the order
GET /checkout/success/{order}Shop\CheckoutSuccessControllerOrder confirmation
GET /account/ordersAccount\OrderController@indexOrder history
GET /account/orders/{order}Account\OrderController@showOrder detail
GET /account/addressesAccount\AddressController@indexAddress management
GET /dashboardInertia pagePage Fortify redirects to after a login with no page to return to
GET /settings/profileSettings\ProfileController@editProfile settings
GET /settings/appearanceInertia pageLight and dark appearance
GET /settings/securitySettings\SecurityController@editPassword and two-factor authentication, after the password confirmation

The checkout posts each step to its own endpoint: checkout/shipping-address, checkout/shipping-option, checkout/prepare-payment and checkout/place-order.

Payment providers send their webhooks to POST /webhooks/{driver}, such as /webhooks/stripe, limited to 300 requests per minute. bootstrap/app.php loads this route outside the web middleware group, so it has no session and no CSRF check.

Architecture

The starter kit separates business logic in Action classes, data structures in DTOs, HTTP handling in controllers, and the interface in Vue components. You can change one part of the storefront without touching the others.

Actions

Actions are single-responsibility classes that hold the business logic. They are resolved from the container, so you can swap an implementation or add dependencies to it. Each one receives the product, the cart or the zone it works on:

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

resolve(AddToCart::class)->handle($product, $variant, quantity: 2);
resolve(FetchDeliveryRates::class)->handle($cart);
resolve(CompleteCheckout::class)->handle($cart);

The checkout uses five actions.

ActionResponsibility
BuildShippingPackagesPacks the cart lines into one package, with their total weight and the largest dimensions, for carrier rate requests
FetchDeliveryRatesQuotes the carriers of the cart's zone and keeps the options in the cart's currency, with a warning for each carrier that fails
FetchPaymentMethodsLists the payment methods enabled on a zone that the storefront can check out with: manual methods and Stripe
CreatePaymentSessionOpens a payment session with the provider for the cart total, or resumes the open one when the amount and currency are unchanged
CompleteCheckoutTurns the cart into an order

CompleteCheckout checks that the payment method is still available on the zone, quotes the delivery option again, and refuses the order when the option is gone or its price went up. It then converts the cart into an order and records the initiated payment. Called again on the same cart, it returns the order it already created, so a double submit or a refreshed Stripe return never creates two orders.

DTOs

Data Transfer Objects give a typed shape to the data passed from the backend to the Vue pages. Each one carries the #[TypeScript] attribute, so the TypeScript Transformer turns it into a type 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 the Shopper models and return an Inertia response that renders the matching page component. The show method of the product page returns a 404 for an unpublished product, then loads the brand, the media, the related products and the variants, each with its prices in the current currency, before it renders shop/product:

app/Http/Controllers/Shop/ProductController.php
$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,
]);

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 can read the authenticated user and the current shop state without fetching them. The shop prop carries the cart count, the selected zone, the active currency, the enabled channels, the countries a visitor can pick, the tax label, and the categories of the header and footer navigation.

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, and useCart exposes the add, update, remove and clear cart actions.

Models

The starter kit publishes models that extend the Shopper models. Category, Channel, Collection, Product and ProductVariant are registered in config/shopper/models.php, so that Shopper and its admin panel use them too. The kit also ships its own User model.

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;

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

HasProductPricing resolves the price of a product or variant in the current currency, for the logged-in customer and the selected zone. The withCurrentPrices scope loads only the prices in the current currency, for the listings. The InteractsWithStorefrontMedia trait appends thumbnail and images attributes to every JSON response, so your Vue components receive media URLs ready to render.

Helpers

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

FunctionPurpose
cartSession()Returns the current cart or creates one with the active currency, the default channel and the selected zone
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 country is selected
cart_context()Returns the cart totals the pages display: subtotal, discount, tax, shipping and total, whether prices include tax, and the subtotal of each line

Type Safety

Three tools give your Vue components the shape of the backend data, so they never guess it.

ToolWhat it provides
WayfinderTyped functions for the named routes and the controller actions, generated into resources/js/routes and resources/js/actions by its Vite plugin when the assets build
TypeScript TransformerTypeScript definitions of the PHP DTOs, written to resources/js/types/generated.d.ts
@shopperlabs/shopper-typesShared domain types (Address, Cart, Order, Product, Zone and more) published as an npm package

The TypeScriptTransformerServiceProvider configures the transformer. After you change a DTO, regenerate the types:

php artisan typescript:transform

Checkout Flow

The checkout is a multi-step process handled by CheckoutController. Each step posts to its own endpoint, validates its data and saves it on the cart through Shopper's CartManager, so a customer who comes back to the checkout resumes at the step they reached.

Step 1 - Shipping Address. The customer enters a new address or selects one of their saved addresses in the countries of their zone. The address is saved on the cart as the shipping and the billing address, with the country selected in the storefront.

Step 2 - Delivery Options. FetchDeliveryRates builds the package with BuildShippingPackages and quotes the carriers of the cart's zone for that address, from the default inventory location. The customer selects a delivery option.

Step 3 - Payment. FetchPaymentMethods lists the payment methods enabled on the cart's zone. For a manual method, such as cash on delivery, placing the order runs CompleteCheckout, then starts the payment through Shopper's PaymentProcessingService and shows the confirmation page.

For Stripe payments, choosing the method runs CreatePaymentSession, which opens a Stripe PaymentIntent for the cart total without creating an order, and the payment step renders the Stripe Payment Element through the StripePaymentForm component and the useStripeElements composable. Once Stripe confirms the payment, it sends the customer back to /checkout/stripe-return. The StripeReturnController retrieves the PaymentIntent and runs CompleteCheckout when the payment is authorized, captured or processing. When the order cannot be created, it cancels the authorization or refunds the capture.

The payment status of the order comes from the provider's webhooks, which PaymentWebhookController hands to Shopper. The route answers 404 until the Stripe driver is configured. The Stripe page covers the keys and the events to select for the endpoint https://your-store.test/webhooks/stripe. Keep the scheduler running, as described in Run the Scheduler and a Queue Worker: Shopper applies the events that arrived before their order existed on a schedule.

Zones and Currency

The starter kit uses Shopper's zones for multi-currency and regional pricing. The ZoneSelector component in the footer lets customers pick their country among the countries of the enabled zones. The ZoneSessionManager then stores the country code in the session and resolves it to a CountryByZoneData DTO with the zone, the country and its currency. Prices across the storefront follow the zone's currency through the shared shop prop.

When a customer changes country, ZoneSessionManager moves the cart to the new zone. It removes the lines that have no price in the new currency and tells the customer, prices the other lines in the new currency, and resets the delivery option, the payment method and any open payment session.

When no country is selected, the storefront uses the default currency of your store from shopper_currency(), and the cart has no zone, so the checkout offers no delivery option or payment method.

The current_tax_label() helper reads the tax zone of the selected country to display "TTC" (tax-inclusive) or "HT" (tax-exclusive) next to prices.

To let customers pick a country, create at least one enabled zone in the admin panel.

Customization

Once installed, every file belongs to your project. The frontend lives in resources/js and the storefront logic in app/. These are the places you will change most often.

Styling

All pages use shadcn-vue components and Tailwind CSS v4. The colors are CSS variables in resources/css/app.css: one set under :root for the light appearance and one under .dark. Change --primary in both to give the storefront your brand color. The UI primitives live in resources/js/components/ui/, the storefront components such as the product card in resources/js/components/shop/, and the header and footer in resources/js/layouts/storefront/.

The kit's components.json configures the shadcn-vue CLI, so a component you add lands in resources/js/components/ui/ next to the others:

npx shadcn-vue@latest add switch

Pages

Each page is a Vue single-file component in resources/js/pages/. Edit a .vue file to change the layout or content of its page. 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

To give a group of pages another layout, add a case to that callback.

Checkout

The checkout actions live in app/Actions/Checkout/. Each one handles one concern, so you can change how shipping rates are calculated without touching the payment logic. The checkout page itself is resources/js/pages/shop/checkout.vue, and the Stripe form resources/js/components/shop/stripe-payment-form.vue.

To add a payment provider, implement it with Shopper's payment system, register it in the admin panel, and enable it on the zones where customers can use it. FetchPaymentMethods only lists the drivers of its SUPPORTED_DRIVERS constant, manual and stripe, so add the new driver there once its payment step and return page exist.

Adding Pages

A new page takes a controller, a named route in routes/web.php, and a Vue component under resources/js/pages/. Name the page under shop/ so it renders with the storefront header and footer. This controller renders the shop/about page:

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');
    }
}

This route serves the page at /about, under the name about:

routes/web.php
use App\Http\Controllers\AboutController;

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

This component renders the title of the page inside the Container of the storefront:

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 models in app/Models/. They extend the Shopper models, so everything Shopper defines on them keeps working.

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