Skip to main content

​
Theme Development

A Shoppex theme is a standalone frontend app that renders a storefront UI. You can choose the UI framework:
  • React
  • Vue
  • Svelte
  • Anything else that can build to static files
But a few things are fixed by the Shoppex platform:
  • Themes are built with a Vite-style build pipeline
  • The build output must be a dist/ folder with dist/index.html and assets
  • Themes use the Shoppex Storefront SDK for data (store, products, cart, checkout handoff)
If you want to build themes with Vue/Svelte/etc: totally fine. Just keep the build contract the same (bun run build → dist/).

​
Theme vs SDK (one sentence)

Theme = UI/UX. SDK = data + cart + checkout behavior.

​
Start Here

Most people should start with one of these goals:
  1. I want AI to help me customize a theme Start with Build and Customize a Theme with AI
  2. I want to run a theme locally first Start with Quickstart
  3. I want to edit a real hosted theme locally and sync it back Start with Hosted Theme Sync
  4. I want the technical platform details Read Theme Control Plane and the reference pages after that
If you’re unsure, start with the AI guide. If you only want local setup first, start with quickstart. If you already have a hosted theme and want pull/push, start with Hosted Theme Sync. For deep integration or tooling, use the advanced pages.

​
Most Common Journeys

Customize with AI

Best path for beginners using Claude Code or Codex. Inspect first, change one thing, validate, preview, then publish.

Run Locally First

Start a reference theme on localhost, then come back to the AI guide once you want to edit safely.

Sync A Hosted Theme

Pull a real hosted Shoppex theme into a local folder, edit it in your own tools, then push a validated draft back.

Go Deeper

Learn the shared system behind inspect, apply, validate, preview, publish, CLI, and MCP.

​
More Topics

  • AI Workflows — Advanced CLI and MCP-driven theme editing
  • Core Contract — The framework-agnostic rules your theme must satisfy
  • Build Pipeline — How Shoppex builds, injects data, and deploys to the edge

​
Reference Theme In This Repo

Our reference implementations are Vite + React:
  • themes/default
  • themes/classic
If you want to understand how things work in practice, start with:
  • themes/default/src/main.tsx
  • themes/default/index.html

​
Source Of Truth (Architecture)

If you need the “big picture”:
  • the theme contract is documented here under Core Contract, Runtime & SDK, and Build Pipeline
  • the serving infrastructure is intentionally described at a high level (implementation details may change)