Skip to content

React Starter Kit

A Shopper storefront built with Inertia, React 19, shadcn/ui and Tailwind CSS v4.

The React Starter Kit is a complete storefront for Shopper, built with Inertia.js and React 19. It keeps the full power of Laravel on the backend, with no separate API layer to maintain, while delivering a modern single-page application experience on the frontend. The design system uses shadcn/ui components and Tailwind CSS v4, and every route is fully type-safe thanks to Laravel Wayfinder and a PHP-to-TypeScript transformer.

React Starter Kit storefront

Prerequisites

The kit's manifest requires these PHP, Laravel and Shopper versions, and its Vite version needs the Node.js versions below.

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

The installer downloads the kit, reads its manifest, copies all storefront files into your project, and 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: database migrations, storage symlink creation, npm install, and the frontend asset build.

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

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

Project Structure

The starter kit publishes files into standard Laravel directories. The backend is shared with the Vue Starter Kit; only the resources/js frontend differs. 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/
│   ├── 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/ui primitives (button, dialog, select, ...)
├── hooks/             # 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
├── types/             # Shared and generated TypeScript types
└── app.tsx            # 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

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 React components.

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 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\SearchControllerProduct search by name
GET /cartShop\CartController@indexShopping cart

Cart mutations are exposed as their own throttled endpoints: 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.

Authenticated Routes

These routes use the auth and verified middleware, except the profile page (GET and PATCH /settings/profile), which only requires a login. The verified middleware blocks unverified customers only when your User model implements Laravel's MustVerifyEmail contract, which the kit's model does not.

RouteControllerDescription
GET /checkoutShop\CheckoutController@indexMulti-step checkout flow
GET /checkout/payment/{number}Shop\StripePaymentControllerStripe Payment Element
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 /settings/profileSettings\ProfileController@editProfile settings
GET /settings/appearanceInertia pageDark mode / 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 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, HTTP handling in controllers, and UI in React 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

Order creation is wrapped in CreateOrder, which uses Cache::lock for idempotency and verifies cart ownership before converting the cart into an order.

DTOs

Data Transfer Objects provide type-safe structures for data passed between the backend and the React 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
CountryByZoneDataZone session data (zone ID, country code, currency code)
PriceDataCurrent price, compare-at 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, wrap data in DTOs, and return an Inertia response that renders the matching page component.

use App\Models\Product;
use Inertia\Inertia;
use Inertia\Response;

public function show(Product $product): Response
{
    return Inertia::render('shop/product', [
        'product' => $product->load('variants', 'media'),
    ]);
}

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 global data with every page, so your components always have access to the authenticated user and the current shop state without re-fetching it. The shop prop carries the cart count, the selected zone, the active currency, available channels and zones, the tax label, and navigation categories.

'shop' => fn (): array => [
    'cart_count' => $cart?->lines->sum('quantity') ?? 0,
    'zone' => $zone,
    'currency' => current_currency(),
    'tax_label' => current_tax_label(),
    // navigation categories, channels, available zones ...
],

On the frontend, the useShop hook reads this shared data, including the cart count, and useCart exposes the cart mutations: add, update, remove, and clear.

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\Concerns\InteractsWithStorefrontMedia;
use App\Traits\HasProductPricing;
use Shopper\Models\Product as Model;

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

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 InteractsWithStorefrontMedia trait appends thumbnail and images attributes to every JSON response, so your React components receive ready-to-use media URLs.

CheckoutSession

The CheckoutSession class defines constants for the session keys that hold the customer's checkout choices: addresses, delivery option, and payment method.

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

This kit is type-safe end to end. Three tools work together so your React components never guess at the shape of backend data.

ToolWhat it provides
WayfinderTyped route helpers generated from routes/web.php, so shop.product becomes an importable function
TypeScript TransformerGenerates TypeScript definitions from your PHP DTOs and enums into resources/js/types
@shopperlabs/shopper-typesShared domain types (Address, Cart, Order, Product, and enums) published as an npm package

The TypeScriptTransformerServiceProvider registers the transformer and writes the types to resources/js/types/generated.d.ts. Run php artisan typescript:transform after changing a DTO to refresh the TypeScript types your components import.

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. 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. For a manual method 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 the shipping cost. The controller then initiates payment processing through Shopper's PaymentProcessingService.

When the customer selects Stripe, the checkout creates a Stripe PaymentIntent before any order exists and renders the Stripe Payment Element on the payment step, through the StripePaymentForm component and the useStripeElements hook. Once the payment is confirmed, Stripe sends the customer back to checkout/stripe-return, where the kit checks the PaymentIntent and only then creates the order. The StripeWebhookController checks the webhook signature and updates the order's payment status when Stripe reports a payment as authorized, captured, failed, canceled, or refunded.

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 customer picks a country, the ZoneSessionManager stores its country code in the session and resolves it on each request into a CountryByZoneData DTO with the zone, the country, and the currency code. All prices across the storefront update to reflect 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. Here are the most common customization paths.

Styling

All views use shadcn/ui 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 chrome is in resources/js/layouts/storefront/.

Pages

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

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, then add the payment method in your admin panel and enable it on your zones. The checkout will automatically pick it up through FetchPaymentMethods.

Adding Pages

Create a controller, register a named route in routes/web.php, and add the matching React component under resources/js/pages/. The layout is picked from the page name in resources/js/app.tsx: pages under shop/ get the storefront header and footer.

app/Http/Controllers/Shop/AboutController.php
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');
    }
}
routes/web.php
use App\Http\Controllers\Shop\AboutController;

Route::get('about', AboutController::class)->name('shop.about');
resources/js/pages/shop/about.tsx
export default function About() {
    return <h1>About Us</h1>;
}

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.

use Illuminate\Database\Eloquent\Builder;

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

Last updated on

Edit on GitHub