> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Themes

> Choose between an Easy visual theme and an Advanced code storefront, then see how Shoppex serves both.

Every Shoppex storefront runs in one of two lanes: Easy, a visual ThemeDocument you edit in the Builder, or Advanced, your own React and Vite project.

## Easy or Advanced

|               | Easy                                                     | Advanced                                                        |
| ------------- | -------------------------------------------------------- | --------------------------------------------------------------- |
| Source        | A ThemeDocument: pages, ordered blocks, and settings     | Your own React and Vite project                                 |
| You edit with | The Theme Builder, the CLI, or AI tooling                | Your code editor, the CLI, or AI on your source files           |
| Build step    | None. The Builder saves structured data directly.        | Each publish installs your dependencies and builds the project. |
| Rendered by   | The Shoppex block renderer                               | Your built output, served as a locked build that never changes  |
| Safety net    | A revision history. Publishing an old draft restores it. | Your own version control, plus the build history in Shoppex     |
| Best for      | Fast setup and guided editing, with no code required     | Full control over markup, components, and behavior              |

If you are not sure which lane to pick, start Easy. The two lanes do not mix inside one storefront, so switching from Easy to Advanced replaces the ThemeDocument with a new source project.

<CardGroup cols={2}>
  <Card title="Set up an Easy theme" icon="palette" href="/storefront/visual-themes">
    Edit pages and blocks in the Theme Builder, then preview and publish.
  </Card>

  <Card title="Set up an Advanced storefront" icon="code" href="/storefront/code-storefronts">
    Bring your own React and Vite source, or import an existing project.
  </Card>
</CardGroup>

## Installable themes

Open **Store → Themes** to install one of five active themes: `default`, `starlight`, `pulse`, `clean-minimal`, and `classic`. Each one creates a ThemeDocument you can edit in the Builder right away.

<Tip>
  If you are not sure which theme to start from, use `default`.
</Tip>

Five older themes are retired: `apex`, `nebula`, `phantom`, `shadow`, and `vault`. An existing storefront on one of these keeps rendering, and you can still export and import it. You cannot create a new theme on a retired scheme.

## Easy: the ThemeDocument contract

A ThemeDocument splits ownership across four layers.

| Layer                     | Owns                                                                   |
| ------------------------- | ---------------------------------------------------------------------- |
| ThemeDocument             | Pages, ordered blocks, design tokens, content settings, and custom CSS |
| Shoppex backend           | Validation, drafts, revisions, and catalog and route context           |
| Block renderer            | HTML, structured data, and renderer-owned styles                       |
| Platform commerce runtime | Cart, product actions, coupons, and checkout handoff                   |

Every block has a stable ID, a registered type, a visibility flag, and typed settings. An unknown block type or an invalid setting fails validation. Shoppex does not fall back to a different block or a guessed value in its place.

The backend supplies request data such as products, collections, locale, and currency. A theme setting never calculates a final price, a stock level, payment eligibility, or a checkout rule. Those stay server-side, on every theme. See [Visual themes](/storefront/visual-themes) for the editing workflow itself.

## Choosing a runtime or SDK

| You are building                                       | Use                                                                         |
| ------------------------------------------------------ | --------------------------------------------------------------------------- |
| An Easy storefront hosted by Shoppex                   | The Theme Builder, or the CLI and API against ThemeDocument settings        |
| An Advanced storefront hosted by Shoppex               | Your own React and Vite source, edited with the CLI, the code editor, or AI |
| A storefront you host yourself, for example on Next.js | `@shoppexio/storefront`                                                     |
| A trusted server integration                           | `@shoppexio/sdk` and the `/dev/v1/*` Developer API                          |

A storefront hosted by Shoppex, Easy or Advanced, includes the platform commerce runtime automatically. A block does not start its own cart SDK or duplicate checkout logic.

A storefront you host yourself imports `@shoppexio/storefront` and owns its own rendering and deployment. It still calls Shoppex APIs for the official commerce data and buyer actions.

## How storefronts serve

Shoppex resolves your domain at the edge and renders the published document or artifact from there.

* Publishing a ThemeDocument creates a new document revision. That revision never changes again.
* Publishing an Advanced storefront creates a new build. That build never changes again.
* A renderer update ships on its own revision, independent of your document.
* Public assets use versioned URLs, so a given URL always returns the same file.
* Custom domain routing and cache purges are a Shoppex responsibility, not yours.
* A protected download or a private draft never appears through the public asset path.

If a shop has no valid published document or artifact, the storefront returns the normal unavailable response. Shoppex does not fall back to another theme or an older source.