Skip to main content

​
Local Development

Themes are just frontend apps, but they still need two things to load real data:
  • which shop to load (VITE_SHOP_SLUG)
  • which API base URL to call (VITE_API_BASE_URL)
If you do not run a backend locally, set VITE_API_BASE_URL=https://api.shoppex.io. Otherwise localhost will often fall back to http://localhost:3001.

​
Environment Variables

VariableWhen to useExample
VITE_SHOP_SLUGAlways in local devacme
VITE_API_BASE_URLIf you do not run the backend locallyhttps://api.shoppex.io
VITE_USE_MSWIf you want mock datatrue

​
Sync A Hosted Theme Locally

If you want to build against a real Shoppex-hosted theme source, use the Shoppex CLI: 
shoppex auth login --api-key shx_your_key
shoppex theme pull --theme theme_123 --out ./my-theme
cd ./my-theme
VITE_API_BASE_URL=https://api.shoppex.io VITE_SHOP_SLUG=acme bun run dev
When you are ready to sync your local changes back: 
shoppex theme push --preview
Key behaviors:
  • pull stores .shoppex/theme.json so later CLI commands know which theme you linked
  • push uploads the full local source snapshot and validates automatically
  • push never publishes automatically
  • If the remote draft changed since your last pull, push stops with a revision mismatch unless you use --force
If you need the full onboarding flow, including where to create the scoped API key in the dashboard, read Hosted Theme Sync. 
VITE_API_BASE_URL=https://api.shoppex.io VITE_SHOP_SLUG=acme bun run dev

​
Common Mistake: Localhost Calls http://localhost:3001

In the reference theme, the runtime logic is:
  • if the theme runs on a production host, it uses https://api.shoppex.io
  • if the theme runs on localhost, it uses VITE_API_BASE_URL or falls back to http://localhost:3001
So if you start the theme locally and you do not set VITE_API_BASE_URL, it may try to call http://localhost:3001. Fix: 
VITE_API_BASE_URL=https://api.shoppex.io VITE_SHOP_SLUG=acme bun run dev

​
How Shop Slug Is Resolved

The reference theme resolves the shop slug like this (simplified):
  • If VITE_SHOP_SLUG is set (and you are on localhost), use that.
  • If the host is {shop}.myshoppex.io, derive {shop} from the hostname.
  • If it is a custom domain, call the API to resolve the shop by domain.
If you are on localhost, always set VITE_SHOP_SLUG.

​
Source

Reference implementation:
  • themes/default/src/main.tsx

​
Next Steps

Hosted Theme Sync

Full onboarding for API key setup, pull, local dev, push, preview, and publish.

Core Contract

What your theme must output (dist/) and what Shoppex runs (bun install, bun run build).

Troubleshooting

Common problems and quick fixes.