Skip to main content
An Easy theme is a ThemeDocument: a set of pages built from ordered blocks, each with typed settings. Edit it in the Theme Builder, or automate it with the CLI and API.

​
What settings cover

ThemeDocument settings are structured data, validated against the theme’s schema. They cover:
  • Colors, typography, spacing, and shape tokens
  • Page and block content
  • Block visibility and variants
  • Approved custom CSS
Fetch the current settings before you update them. An update sends the complete validated settings object, so an omitted key removes that value.
Settings hold presentation data only. Do not store secrets in them. Do not reproduce pricing, stock, payment, or checkout rules there. Those stay server-side.

​
Blocks and stable IDs

Each block on a page has a stable ID, a registered type, a visibility flag, and typed settings. The ID stays the same when you reorder or edit the block. A later automated update or an AI edit targets that ID, so a changed ID looks like a deleted block plus a new one. An unknown block type or an invalid setting fails validation. Shoppex does not select a fallback block or guess a value in its place.

​
The editing loop

The Theme Builder holds the source of truth for a draft.
1

Inspect

Open the page in the Builder, or fetch the current document and settings, before you change anything.
2

Edit

Change only the page, block, or setting you intend to update.
3

Preview

Check every page type that uses the changed block: product, collection, content, and system pages.
4

Save

Saving stores your draft. It does not change the live storefront.
5

Publish

Publishing validates the document and creates a new revision. Visitors see the new revision only after it completes.

​
Revisions and conflicts

Every publish creates a new revision. A published revision never changes afterwards, so a visitor never receives a half-written document. Another editor, an AI edit, or a CLI push can save a newer draft while you work. If that happens, your save or publish is rejected with a revision conflict instead of silently overwriting that work. If you get a revision conflict, reload the latest draft. Then reapply your change on top of it. For a self-hosted headless application, use @shoppexio/storefront instead of the Theme Builder. See Themes for how the two compare.