Skip to content

React Starter Kit

A Shopper storefront built with Inertia, React 19, shadcn/ui and Tailwind CSS v4, installed into your Laravel application with one command.

The React Starter Kit is a storefront for Shopper built with Inertia and React 19. Laravel controllers query the Shopper models and pass the data to React 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/ui 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

Create a Laravel application and install Shopper as described in Installing a Starter Kit, then run the installer with the package name of the kit:

php artisan shopper:kit:install shopperlabs/react-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 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

The post-install commands have already migrated the database, linked the storage folder and built the front-end assets, so you can start the development server:

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 assets are built into public/build. When you change a file in resources/js or resources/css, build them again with npm run build, or keep npm run dev running while you work so Vite serves the assets and updates the page as you edit.

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 checkout of the kit already renders the Stripe payment step. 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_...
STRIPE_CAPTURE_METHOD=manual

Shopper offers Stripe once the secret key and the webhook secret are set, and the payment step needs the publishable key to load the Stripe Payment Element. Configuration describes each variable. Then create a payment method with the Stripe driver and enable it on your zones, as described in Payment Method Setup.

Stripe sends its webhooks to the kit's endpoint, https://your-store.test/webhooks/stripe. Create it in the Stripe Dashboard with the events listed in Handled Events, and copy its signing secret into STRIPE_WEBHOOK_SECRET.

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/
├── hooks/
├── layouts/
├── lib/
├── pages/
│   ├── account/
│   ├── auth/
│   ├── settings/
│   ├── shop/
│   └── dashboard.tsx
├── types/
└── app.tsx

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/ui primitives. The hooks 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 React 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 React 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 React 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 hook 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 React 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 React 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 hook. 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, as described in 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

Every file the kit copied belongs to your project, so you customize the storefront by editing it. The React code lives in resources/js, the theme in resources/css/app.css, and the data each page receives in the controllers of app/Http/Controllers.

Styling

The theme is a set of CSS variables in resources/css/app.css. The :root block holds the light colors and the .dark block the dark ones, and the @theme block maps each variable to a Tailwind color, so --primary becomes the bg-primary and text-primary utilities. To change the brand color, change --primary in both blocks:

resources/css/app.css
:root {
  --primary: oklch(0.6 0.118 184.704);
}

.dark {
  --primary: oklch(0.704 0.14 182.503);
}

The same file sets the corner radius of the components with --radius and the font with --font-sans. The kit loads Instrument Sans from Bunny Fonts in vite.config.ts, so change both files when you switch fonts. Some pages, such as resources/js/pages/shop/home.tsx, also use Tailwind's zinc colors directly, and resources/js/app.tsx sets the color of the Inertia progress bar.

The primitives in resources/js/components/ui are shadcn/ui components, and components.json configures the shadcn CLI for the kit's paths. To add a component, run the CLI from the root of your project:

npx shadcn@latest add switch

The CLI writes the component to resources/js/components/ui/switch.tsx, and your pages import it like the others:

import { Switch } from '@/components/ui/switch';

Pages

Each page is a React component in resources/js/pages, grouped by area:

FolderPages
pages/shopHome, catalog, product, cart, checkout, order confirmation, categories, category, collection and search
pages/accountOrder history, order detail and addresses
pages/settingsProfile, security and appearance
pages/authLogin, register, password reset and confirmation, email verification and two-factor challenge
pages/dashboard.tsxAccount overview

resources/js/app.tsx picks the layout of each page from its name:

Page nameLayout
shop/*StorefrontLayout, with the store header and footer
account/* and dashboardStorefrontLayout and AccountLayout, the account navigation
settings/*StorefrontLayout, AccountLayout and SettingsSubLayout
auth/*AuthLayout
Any other nameAppLayout, a sidebar layout

The store header and footer live in resources/js/layouts/storefront/store-header.tsx and store-footer.tsx. Edit them to change the logo, the navigation or the footer links.

To change the data a page receives, edit its controller. The home page, for example, receives its featuredProducts, featuredCollections and categories props from app/Http/Controllers/Shop/HomeController.php.

Checkout

The checkout is a single page, resources/js/pages/shop/checkout.tsx, that renders the three steps and lets the customer go back to a step they completed. The Stripe form is the resources/js/components/shop/stripe-payment-form.tsx component, and resources/js/hooks/use-stripe-elements.ts loads Stripe.js and mounts the Payment Element. On the server, each concern has its own action in app/Actions/Checkout, as described in Actions, so you can change how shipping rates are quoted without touching the payment logic.

To add a payment provider, implement it with Shopper's payment system, create its payment method 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 React component in resources/js/pages. Name it under shop/ so it renders inside the store header and footer. This controller renders the shop/about page:

app/Http/Controllers/Shop/AboutController.php
<?php

declare(strict_types=1);

namespace App\Http\Controllers\Shop;

use App\Http\Controllers\Controller;
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 shop.about:

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

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

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

resources/js/pages/shop/about.tsx
import { Head } from '@inertiajs/react';
import Container from '@/components/shop/container';

export default function About() {
  return (
    <>
      <Head title="About Us" />

      <Container>
        <h1 className="py-16 text-4xl font-bold">About Us</h1>
      </Container>
    </>
  );
}

The next asset build adds an about function to resources/js/routes/shop, so the header or any other page can link to the page with shop.about.url(), after import * as shop from '@/routes/shop'.

Models

Add methods, scopes or relationships to the models in app/Models. As described in Models, config/shopper/models.php registers them, so Shopper and its admin panel work with your version. For example, add a featured scope next to withCurrentPrices in the product model:

app/Models/Product.php
final class Product extends Model
{
    #[Scope]
    protected function featured(Builder $query): void
    {
        $query->where('featured', true);
    }
}

The home page query in HomeController can then call ->featured() in place of ->where('featured', true).

Last updated on

Edit on GitHub