Skip to main content

​
Core Contract (Framework-Agnostic)

This page describes what Shoppex expects from a theme, regardless of whether you use React, Vue, Svelte, or something else.
Your UI framework is your choice. The only hard requirement is: bun run build must produce dist/index.html.

​
Build Output

Your theme must build to a dist/ folder:
  • dist/index.html
  • dist/assets/* (hashed assets are recommended)
If your build does not produce dist/index.html, Shoppex cannot deploy it.

​
Build Commands (What Shoppex Runs)

On the build system, Shoppex will run: 
bun install
bun run build
That means your theme project must have:
  • a package.json
  • a build script that produces dist/

​
Optional: Initial Data Injection

If your index.html contains this placeholder: 
<!--initial-data-->
Shoppex will inject a script tag into the built dist/index.html:
  • It sets window.__SHOPPEX_INITIAL__ with { store, products, groups }
  • Your theme can use it to render instantly (SSR/SSG or “fast first paint”)
If your theme does not contain the placeholder, injection is skipped.

​
Minimal “Hello Theme” Checklist

1

Install

bun install
2

Develop

bun run dev
3

Build

bun run build → creates dist/index.html
4

SDK

Load the Shoppex SDK (CDN or npm) and call init(...).
5

Data

Fetch storefront data (store + products + groups).

​
Next Steps

Runtime & SDK

SDK init, storefront fetching, and domain resolution.

Build Pipeline

How Shoppex builds and publishes themes (install, build, optional injection, deploy).
This page describes the stable contract. Infrastructure details (how/where files are hosted) are internal and may change.