Skip to main content

​
Serving & Caching (Edge)

After a theme is built and published, Shoppex serves it as static files through an edge layer (close to the customer). As a theme developer, you do not need to run a server. Your job is to:
  • build to dist/
  • make sure dist/index.html references the assets that actually exist in dist/

​
Request Flow (Simplified)

  1. Customer visits https://{shop}.{storefront-domain}/...
  2. Shoppex resolves which shop/theme should serve that domain
  3. The edge layer returns index.html and your built assets (JS/CSS/images)

​
Cache Rules (In Human Terms)

  • index.html should not be cached long (so updates show quickly)
  • hashed assets under /assets/*-[hash].* can be cached “forever”

​
Debugging Tips

Try, in order:
  1. Hard refresh (Cmd+Shift+R / Ctrl+Shift+R)
  2. Confirm you are on the correct shop domain (and not a preview link)
  3. Republish the theme (so the platform can pick up the new dist/)
This almost always means an asset path mismatch.Check:
  • your build actually wrote the file to dist/ (e.g. dist/assets/...)
  • dist/index.html references the same filename/path
  • you are not hard-coding absolute paths that break on a different domain
Check:
  • bun run build really produces dist/index.html
  • you published the theme successfully (local build output alone is not “live”)
Shoppex sets Cache-Control headers based on file type:
  • index.html uses short-lived or no-cache headers so updates are visible quickly
  • Hashed assets (JS/CSS with content hashes in the filename) use long-lived cache headers since the filename changes when content changes

​
Custom Domains

Shoppex can serve storefronts on custom domains. When a customer visits a custom domain, the edge layer resolves which shop/theme to serve via the domain lookup API. Theme developers do not need to configure anything — custom domain support is handled at the platform level.

​
Next Steps

Build Pipeline

Understand what happens during publish (install, build, optional injection, deploy).

Troubleshooting

Quick fixes for the most common edge serving issues.