Copy page

Theme SDK

A Wocart theme is an Astro storefront. Two published packages power it:

@wocart/theme is what lets a merchant change a theme's text, images, colors, spacing and section order in Wocart Studio without touching its code. It is a small contract, not a framework: your Astro project, components and CSS stay yours.

This guide follows @wocart/theme 4.1.0 and @wocart/storefront 3.1.0, which read platform v7.

Start with the theme starter. npm create wocart-theme@latest creates a complete theme on both packages: every page a store has, every platform feature, three languages, both hosts, Studio support and its tests. You restyle and extend it instead of writing the plumbing. The guide's examples come from it. You can also build a theme from scratch with the two packages; the starter is the faster way to the same result.

Do you need it?

An editable theme costs more setup than a fixed one, because every editable choice is declared, stored and checked. That cost buys a theme any store can install and any merchant can change safely.

How it works in one picture

Code
   code (you write it)                    data (the store saves it)
 ┌──────────────────────────┐          ┌────────────────────────────┐
 │ defineComponent(...)     │          │ page document (JSON)       │
 │   fields, slots, load    │          │   { version, surface,      │
 │ defineTheme(...)         │          │     sections: [instances] }│
 │   surfaces, areas,       │          │ theme settings (JSON)      │
 │   settings, content      │          │ text edits per language    │
 └────────────┬─────────────┘          └──────────────┬─────────────┘
              │ themeManifest()                       │ storefront client
              ▼                                       ▼
   /wocart-theme.json ──► Wocart Studio     resolveSurfaceDocument()
   (what is editable)      writes data ──►  InstanceView renders your
                                            .astro components

• Code is the catalog. Each component you want editable gets a definition: its type, its fields, where it may go, and an optional server-side load.
• Data is the page. A page is a document: an ordered list of component instances with their saved values. The theme ships a default document for every page; a store may save its own.
• The manifest connects them. It is the code half turned into JSON, so Wocart Studio knows what can be edited without running your theme.
• Reading never breaks a page. A saved document is untrusted: the SDK repairs what it can, reports the rest, and never throws the page away over one bad section.

Words you will see

What the package guarantees

• One typed definition per component. Field keys, kinds and select options keep their literal types; the component's props are derived from the same definition (InferProps), so the two cannot drift.
• Safe reads. parsePageData, validatePageData and resolveSurfaceDocument turn any saved value into a renderable page plus a list of issues. Only a broken envelope makes a document unusable, and then the theme's default renders.
• Layout rules that hold. Slots, allowed types, required and fixed blocks, placement and limits are applied by the same code for the renderer, the reader and every editor.
• Safe values. Links, colors, images, rich text, style and color schemes are closed formats. A saved value cannot carry a javascript: link, raw CSS or HTML.
• One renderer. InstanceView.astro resolves values, runs load, renders your component, and places its blocks.
• The editor plumbing. The manifest, document operations, preview markers, the preview bridge, settings, content packs and plural messages.

What it does not do

• It does not fetch commerce data. Reads go through the @wocart/storefront client a load receives.
• It does not save anything. Wocart Studio and the platform write documents, settings and text edits; a theme only reads them.
• It does not upload images, define your CSS, or replace Astro.

The rules every theme follows

Each rule below exists because breaking it fails a merchant or a shopper in a way a test of the theme alone would not show. The Enforced by column says what catches a break: the SDK (for every theme), or the starter's tests (a theme made with the starter runs them with npm test; a theme built from scratch copies them).

The starter, file by file lists each test and the command that runs it.

Install

The starter installs both packages for you. To add them to a project of your own:

Code
npm install --save-exact @wocart/theme@4.1.0 @wocart/storefront@3.1.0 zod

Where to go next