Build
Themes & .cos
.cos is the one distribution format for themes: a zip with a cos.json manifest. Block themes feed the visual editor; static themes ship your own framework build — either way, themes are data, and no theme code ever executes on CommerceOS servers.
The manifest
# cos.json — at the root of the archive{ "name": "Aurora", "version": "1.2.0", "kind": "static", "entry": "index.html", "regions": [ { "name": "home-hero" }, { "name": "footer-promo" } ]}# kind "blocks" → a block-JSON theme for the visual editor# kind "static" → a prebuilt framework app served from the CDN
| Field | Type | Description |
|---|---|---|
| namereq | string | Display name (≤ 120 chars). |
| versionreq | semver | Every upload is a new immutable version. |
| kindreq | "blocks" | "static" | What the archive contains. |
| entry | string | Static kind: the HTML entry (usually index.html). |
| regions | { name }[] | Content regions the theme consumes — becomes the merchant’s editable surface (see regions). |
| engines | object | Blocks kind: the block-schema version the theme targets. |
Package a static theme
Any framework that produces static output works — Next export, Vite, Astro, SvelteKit static. Build, stamp a manifest, validate, pack:
npm run build # your framework build → dist/npx cos init dist --name "Aurora" # writes dist/cos.json (edit regions/entry)npx cos validate dist # schema + limits + entry checksnpx cos pack dist -o aurora-1.2.0.cos # zip with the manifest at the root
Deploy, publish, roll back
- Upload the
.cosin Admin → Themes → Import. Importing never activates anything. - Publish switches the storefront to that version. Static bundles are served from immutable, version-scoped storage paths — cacheable forever.
- Rollback is repointing: previous versions never mutate, so reverting is instant and needs no cache purge.
Static themes still get live data: the served app is yours — call the Storefront API with a publishable key and render regions for merchant-editable slots. The SDKs are built for exactly this shape.