Skip to main content

​
Theme Package Format

A Shoppex theme is a Vite app project. Here’s what needs to be in it.
A theme is an app project. Shoppex builds it with Bun and serves the static output from dist/.

​
Required (Practical Minimum)

You need:
  • package.json with dev and build scripts
  • index.html
  • src/* (your app code)
  • theme.manifest.json (metadata for listing)
  • theme.config.ts (settings + sections)

​
Example File Tree

my-theme/
  index.html
  package.json
  public/
    preview.png
    favicon.svg
  src/
    main.ts
  theme.config.ts
  theme.manifest.json

​
theme.manifest.json

This is metadata used for listing and tooling (simplified):
  • id
  • name
  • version
  • preview (optional)
  • features (optional)
  • techStack (optional)
Example (minimal): 
{
  "id": "my-theme",
  "name": "My Theme",
  "version": "1.0.0",
  "preview": "preview.png"
}

​
What Matters Most

Build Script

bun run build must produce dist/index.html.

Theme Config

theme.config.ts defines settings and sections.

Initial Data

Optional <!--initial-data--> injection for faster first render.

​
Keep Versions Aligned

If your theme has multiple version fields, keep them consistent:
  • theme.manifest.json version
  • package.json version (if set)
  • theme.config.ts version (if you include it)
Lockfiles (bun.lockb, pnpm-lock.yaml, yarn.lock) are treated as read-only in the online theme editor. Don’t rely on editing them through the dashboard or API — manage dependencies locally and push.
The manifest is plain JSON. The exact internal parsing rules can evolve, but the goal stays the same: identify your theme and its version, and provide optional metadata for tooling.

​
Next Steps

Import/Export/Upgrades

How theme editing and upgrades work (conceptually).

Troubleshooting

Common failures when a theme package is incomplete or misbuilt.