Skip to main content

​
Hosted Theme Sync

Use this workflow if you want to edit a real Shoppex-hosted theme locally instead of using the builder. The workflow: create a theme development API key in the dashboard, pull the hosted theme locally, develop with real storefront data, push your changes back as a draft, then preview and publish.

​
What You Need

You need:
  • a hosted Shoppex theme ID like theme_123
  • a Shoppex API key with themes.read and themes.write
  • Bun installed locally

​
Step 1: Create A Theme Development Key

In the Shoppex dashboard:
  1. open Settings -> Developer
  2. open the API Keys section
  3. click Create API Key
  4. choose the Theme Development preset
  5. copy the secret immediately
The dashboard creates a key with:
  • themes.read
  • themes.write
This key can sync theme source but it never auto-publishes anything.

​
Step 2: Run The CLI

If your environment uses the published package, start with: 
npx @shoppexio/cli auth login --api-key shx_your_key
If you are working from this repo instead, run: 
bun packages/cli/bin/shoppex.mjs auth login --api-key shx_your_key
If you want shorter commands while working from the repo, create a shell alias: 
alias shoppex="bun /absolute/path/to/shoppex/packages/cli/bin/shoppex.mjs"
Then the rest of the commands work exactly as written below.

​
Step 3: Pull The Hosted Theme

shoppex theme pull --theme theme_123 --out ./my-theme
cd ./my-theme
What pull does:
  • downloads the current hosted theme source as a ZIP
  • extracts it into your local folder
  • writes .shoppex/theme.json with the linked themeId and sourceRevision
That metadata is important because the next push checks whether the remote draft changed since your last pull.

​
Step 4: Run The Theme Locally

If you want real storefront data without running the backend locally: 
VITE_API_BASE_URL=https://api.shoppex.io VITE_SHOP_SLUG=acme bun run dev
Your local code runs on localhost while data comes from https://api.shoppex.io — the hosted theme remains your source of truth for push and publish.

​
Step 5: Push Your Local Changes

When you are ready to sync your local draft back to Shoppex: 
shoppex theme push --dir ./my-theme
If you are already inside the pulled folder, this is enough: 
shoppex theme push
What push does:
  • uploads the full local source snapshot
  • replaces the current remote draft source
  • deletes remote draft files that you deleted locally
  • runs validation automatically
  • never publishes automatically

​
Step 6: Preview And Publish

Start a preview after a successful push: 
shoppex theme preview --theme theme_123
Or ask push to start preview immediately: 
shoppex theme push --preview
Publish is always explicit: 
shoppex theme publish --theme theme_123

​
Safety Rules

These rules matter for the local sync model:
  • push is a full replace of the remote draft source
  • deleted local files are deleted remotely too
  • push validates automatically
  • push never publishes automatically
  • blocked paths like .git/, node_modules/, dist/, and lockfiles are ignored

​
Revision Mismatch

If someone changed the remote draft after your last pull, push stops with a revision mismatch. Say you pulled revision r12, then another developer changes the draft in the dashboard (now r13). Your push is blocked so you don’t silently overwrite their work. The safe fix is: 
shoppex theme pull --theme theme_123 --out ./my-theme --force
Only use --force on push if you intentionally want to overwrite the newer remote draft: 
shoppex theme push --force

​
Validation Errors After Push

If your upload contains build or validation errors, the draft is still saved. That means:
  • your exact uploaded draft is preserved on the server
  • the CLI returns the validation errors
  • publish stays blocked until you fix the draft
If you push a file with broken JSX, Shoppex keeps that draft so you can debug the real failing snapshot — fix the file locally and push again. 
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
shoppex theme push --preview
shoppex theme publish --theme theme_123

​
Next Steps

Local Development

Understand VITE_API_BASE_URL, VITE_SHOP_SLUG, and localhost behavior.

Theme Control Plane

Learn the shared model behind dashboard, Dev API, CLI, and MCP.

AI Workflows

Use MCP and CLI together when you want an AI assistant to drive the edits.

Troubleshooting

Fix common local-development, sync, and validation issues.