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.
| Requirement | Version |
|---|---|
| PHP | 8.3+ |
| Laravel | 12.68+ or 13.27+ |
| Shopper | 3.0+ |
| Node.js | 20.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-kitThe 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:
| Package | Purpose |
|---|---|
inertiajs/inertia-laravel | Inertia server-side adapter for Laravel |
laravel/fortify | Authentication backend (login, register, password reset, two-factor authentication) |
laravel/wayfinder | Typed route functions generated from your routes |
spatie/laravel-typescript-transformer | TypeScript types generated from the PHP DTOs |
shopper/stripe | Stripe 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 serveThe 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:
- 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
500cents. - A category for the storefront navigation.
- A product that is published, with a price in the zone's currency and stock in an inventory location. A canvas tote bag at
2500cents ($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:
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_CAPTURE_METHOD=manualShopper 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.
| Route | Controller | Description |
|---|---|---|
GET / | Shop\HomeController | Homepage with featured collections, products, and categories |
GET /shop | Shop\ProductController@index | Product catalog with search, a category filter and sorting |
GET /shop/{product:slug} | Shop\ProductController@show | Product detail with variant selection |
GET /categories | Shop\CategoryController@index | All categories |
GET /categories/{category:slug} | Shop\CategoryController@show | Products in a category |
GET /collections/{collection:slug} | Shop\CollectionController@show | Products in a collection |
GET /search | Shop\SearchController | Search products by name, from 2 characters |
GET /cart | Shop\CartController@index | Shopping 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.
| Route | Controller | Description |
|---|---|---|
GET /checkout | Shop\CheckoutController@index | Multi-step checkout flow |
GET /checkout/stripe-return | StripeReturnController | Return URL of a Stripe payment, creates the order |
GET /checkout/success/{order} | Shop\CheckoutSuccessController | Order confirmation |
GET /account/orders | Account\OrderController@index | Order history |
GET /account/orders/{order} | Account\OrderController@show | Order detail |
GET /account/addresses | Account\AddressController@index | Address management |
GET /dashboard | Inertia page | Page Fortify redirects to after a login with no page to return to |
GET /settings/profile | Settings\ProfileController@edit | Profile settings |
GET /settings/appearance | Inertia page | Light and dark appearance |
GET /settings/security | Settings\SecurityController@edit | Password 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.
| Action | Responsibility |
|---|---|
BuildShippingPackages | Packs the cart lines into one package, with their total weight and the largest dimensions, for carrier rate requests |
FetchDeliveryRates | Quotes the carriers of the cart's zone and keeps the options in the cart's currency, with a warning for each carrier that fails |
FetchPaymentMethods | Lists the payment methods enabled on a zone that the storefront can check out with: manual methods and Stripe |
CreatePaymentSession | Opens a payment session with the provider for the cart total, or resumes the open one when the amount and currency are unchanged |
CompleteCheckout | Turns 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.
| DTO | Purpose |
|---|---|
AddressData | Structured address data for forms and checkout |
CountryByZoneData | Selected zone and country (zone ID, code and name, country ID, name, code and flag, currency code) |
PriceData | Price with its comparison price and discount percentage |
ProductReviewsData | Product 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:
$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.
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.
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.
| Function | Purpose |
|---|---|
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.
| Tool | What it provides |
|---|---|
| Wayfinder | Typed 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 Transformer | TypeScript definitions of the PHP DTOs, written to resources/js/types/generated.d.ts |
@shopperlabs/shopper-types | Shared 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:transformCheckout 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:
: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 switchThe 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:
| Folder | Pages |
|---|---|
pages/shop | Home, catalog, product, cart, checkout, order confirmation, categories, category, collection and search |
pages/account | Order history, order detail and addresses |
pages/settings | Profile, security and appearance |
pages/auth | Login, register, password reset and confirmation, email verification and two-factor challenge |
pages/dashboard.tsx | Account overview |
resources/js/app.tsx picks the layout of each page from its name:
| Page name | Layout |
|---|---|
shop/* | StorefrontLayout, with the store header and footer |
account/* and dashboard | StorefrontLayout and AccountLayout, the account navigation |
settings/* | StorefrontLayout, AccountLayout and SettingsSubLayout |
auth/* | AuthLayout |
| Any other name | AppLayout, 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:
<?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:
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:
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:
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