Skip to main content

​
Troubleshooting

If you are developing locally without a backend, the most common fix is setting VITE_API_BASE_URL=https://api.shoppex.io.
Check:
  1. Did you set VITE_SHOP_SLUG in local dev?
  2. Did you set VITE_API_BASE_URL to a reachable API?
  3. Did SDK init run before your first API calls?
Quick fix for local dev without backend:
VITE_API_BASE_URL=https://api.shoppex.io VITE_SHOP_SLUG=acme bun run dev
Symptom:
  • The page renders 0 SALES, 0+ PRODUCTS, 0.0 RATING
  • but shoppex.getStorefront() in the network tab returns real data
Cause:
  • Your deployed index.html contains injected window.__SHOPPEX_INITIAL__ that is stale (it was generated at build/deploy time).
  • If your theme only reads initial data and never revalidates, the UI can get stuck on that stale snapshot.
Fix:
  • Make your data hook revalidate in the background after shoppex.init():
    • first render uses window.__SHOPPEX_INITIAL__ (fast)
    • then call shoppex.getStorefront() and update state (fresh)
This happens when:
  • you run the theme on localhost
  • you did not set VITE_API_BASE_URL
Fix:
  • set VITE_API_BASE_URL=https://api.shoppex.io
If you expect window.__SHOPPEX_INITIAL__ but it is missing:
  • make sure your built dist/index.html contains <!--initial-data-->
  • if it is missing, Shoppex will skip injection
Common causes:
  • your dist/index.html references assets that were not written to dist/
  • your build output path is not dist/
Checklist:
  • dist/index.html exists
  • dist/assets/* exists
  • asset URLs in the HTML match the files in dist/
shoppex.init() is synchronous and must run before any SDK method call.Common cause: calling getStorefront() (or any other method) before init(). In that case the SDK throws a NotInitializedError.
Possible causes:
  • Cart might be empty — check shoppex.getCart().length
  • API might be unreachable — check the network tab in devtools
  • If using MSW: checkout is not mocked. You need a real API for checkout to work.
Check:
  1. Verify fetchPublishedThemeSettings() returns data (not null)
  2. Check CSS variable names match your CSS (inspect elements in devtools)
  3. Verify mergeSettings() is called with correct arguments (defaults first, then published)
Check:
  1. Ensure VITE_USE_MSW=true is set in your environment
  2. Check mockServiceWorker.js exists in your public/ directory
  3. Verify handler URL patterns match — handlers use '*/v1/...' wildcard patterns
Server and client must render identical content. Check:
  • InitialDataProvider receives the same data on server and client
  • Avoid Date.now() or Math.random() in the initial render
  • Make sure conditional rendering is consistent between server and client

​
Next Steps

Local Development

Env vars and local behavior (slug resolution, API base URL).

Edge Serving

If it breaks in production, start with serving + caching behavior.