Skip to main content

​
Theme Package Format

This page describes what files matter for a theme project.
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
  src/
    main.ts
  theme.config.ts
  theme.manifest.json
  public/
    favicon.svg

​
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": "theme.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)

​
Notes About Lockfiles

Lockfiles are treated as read-only in some theme editor flows:
  • bun.lockb
  • pnpm-lock.yaml
  • yarn.lock
So do not rely on changing lockfiles inside an online editor.
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.