E-commerce

Stockwell - Everyday-Goods Storefront

Quick Start

Requirements: Node.js 18+ and npm. No environment variables or backend are required to run it. Product photos load from Unsplash, so dev needs a network connection until you swap in your own images.

Download and unzip

After purchase, download the zip from your order confirmation email and unzip it.

Install dependencies

npm install

Start the dev server

npm run dev

Open http://localhost:3000. Routes:

/ - home browse hub, /shop - faceted results
/c/[category], /p/[slug] - category and product pages
/cart, /checkout (4-step, mock), /deals, /wishlist
/account and /account/orders/[id] - orders + tracking

Build and test

npm run build
npm start

# optional
npm test        # Vitest: cart, wishlist, assistant
npm run typecheck

Folder Structure

Next.js App Router. Cart and wishlist are typed, unit-tested reducers persisted to localStorage. The whole catalogue - products, reviews, Q&A, sample orders - lives in one data file.

src/
├── app/
│   ├── layout.tsx            # Instrument Serif + Instrument Sans; theme guard; <Providers>
│   ├── globals.css           # Warm Mono design tokens + CSS (.btn, .link, .plate, .dark-section)
│   ├── page.tsx              # Home - browse hub
│   ├── shop/page.tsx         # Results view (search + facets)
│   ├── c/[category]/page.tsx # Category-scoped results
│   ├── p/[slug]/page.tsx     # Product detail
│   ├── cart/ · checkout/ · deals/ · wishlist/page.tsx
│   └── account/              # Orders, addresses, payment, order detail + tracking
├── components/                # ~60 components - SiteHeader, ProductCard, BuyBox, ProductGallery,
│                               # CheckoutFlow, ResultsView, FilterSidebar, AssistantPanel, ...
└── lib/
    ├── catalog.ts             # THE data file - categories, products, reviews, Q&A, orders
    ├── search.ts              # Pure filter / sort / facet-count engine (URL-driven)
    ├── assistant.ts           # Deterministic AI shopping-assistant matcher
    ├── cart.ts / wishlist.ts  # Pure reducers + Vitest unit tests
    └── seo.ts                 # JSON-LD builders + SITE_URL

Customization

Re-skin the whole store

Every colour is a CSS variable defined once in src/app/globals.css (:root for light, .dark for dark): --ground, --ink, --stone, --tint, --rule, --pigment, and the single --sale red reserved for sale tags. Fonts (Instrument Serif display + Instrument Sans body) load in src/app/layout.tsx.

The catalogue

Everything the store sells is in src/lib/catalog.ts: CATEGORIES (the category rail), PRODUCTS (each with priceCents, optional wasPriceCents for the sale badge and deals page, variants, specs, tags, images, and bundleWith), and sample REVIEWS, QUESTIONS, and ORDERS. All prices are integer cents; shipping and tax rules live in src/lib/cart.ts.

The AI shopping assistant

src/lib/assistant.ts is a pure, deterministic keyword + budget matcher over the catalogue - no API key, works offline. Swap in a real model by replacing the answer() function with a call to your provider and keeping the returned shape; AssistantPanel.tsx does not need to change.

Payment

CheckoutFlow.tsxstep 3 (Payment) has card fields with format-only validation and a commented seam - "Place order" advances to a confirmation and tracking state using mock data; no card is charged. Wire your provider (Stripe, a Merchant of Record, etc.) where the comment marks it.

Deployment

No environment variables are required. Every route is static or SSG.

Set your site URL (optional)

Set NEXT_PUBLIC_SITE_URL to your real domain so canonical URLs, sitemap.ts, robots.ts, and the JSON-LD point at it instead of the fallback demo domain (src/lib/seo.ts).

Deploy

Import the repo on Vercel, or build and run it on any Node 20+ host: npm run build && npm start. No database or runtime services are required.

Still stuck?

Email us at support@thekitbase.app with your order number and we'll help you get set up.