Build the installable ZIP described in Theme package structure, then choose the workflow that matches your stage. Direct imports are for development on your own store. Marketplace versions are immutable release artifacts intended for distribution.
Direct development import#
A direct import runs the package validator and creates a new inactive uploaded theme. It may contain only the surfaces you are currently building, but every surface it declares must be internally complete: its required sections, templates, Vascula source, and referenced block structure must agree. The import does not modify the active theme.
Marketplace validation#
Publishing a marketplace version runs the same package checks plus the complete platform surface floor. The resulting artifact is content-hashed and sealed. Installation fetches those sealed bytes, verifies their hash, validates them again, and writes the theme in one transaction.
A marketplace theme must include a non-empty template for every registered theme-editable surface: catalog pages, content pages, cart and customer pages, store-state pages, order tracking, and the three editable global surfaces. Sections may be reused across related surfaces, so complete coverage does not require a unique implementation for every template.
Install and update behavior#
Operation |
Behavior |
|---|---|
Install |
Creates an inactive marketplace theme and seeds its draft and published compositions from the package templates. |
Activate |
Makes the selected theme live; importing or installing does not activate it automatically. |
Publish a new version |
Seals a new immutable artifact and makes an update available to stores using the listing. |
Update an installed theme |
Updates the existing theme in place. Author-owned sections, blocks, assets, locale files, settings schema, and metafield declarations move to the new version. |
Merchant-owned state |
Compositions, template assignments, theme setting values, locale overrides, theme identity, and active state are preserved during an update. |
Release rules#
Rule |
Why |
|---|---|
Publish a new version for every code change |
A sealed artifact is immutable. |
Use clear version notes |
Merchants need to understand visible changes and whether an update is breaking. |
Preview every routed surface |
Static validation cannot prove the behavior of every CTX value, setting state, or responsive layout. |
Test a real update as well as a clean install |
An update preserves merchant state while replacing author-owned material; that differs deliberately from first installation. |
Do not include repository-only files |
The uploaded archive has a closed allowlist and rejects unknown paths. |
When a package fails validation, use the returned file and reason to fix the source archive, rebuild it, and submit a new version. Do not patch a sealed artifact or rely on files outside the package.