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
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

Core Contract

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

Troubleshooting

Common problems and quick fixes.