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

# Themes Overview

> How SellAuth storefront themes work, how they are rendered, and how to edit them.

## What a theme is

A SellAuth theme is a folder of [Nunjucks](https://mozilla.github.io/nunjucks/) templates, a settings schema, and static assets. Every storefront page is rendered server-side from your theme on each request, so themes control the full HTML output of the shop.

A theme has two halves:

* **Templates** (`.njk` files) define the markup.
* **`schema.json` and `settings.json`** define what a merchant can configure without touching code, and hold the values they picked.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/developers/theme-quickstart">
    Create, pull, and edit your first theme in a few minutes.
  </Card>

  <Card title="Theme Structure" icon="folder-tree" href="/developers/theme-structure">
    Folders, template names, and how routes map to files.
  </Card>
</CardGroup>

## How rendering works

1. A visitor requests a page, for example `/product/my-product`.
2. SellAuth resolves that URL to a **template name**, for example `product`.
3. Your theme's `templates/product.njk` is rendered with the page data (the product, feedbacks, shop settings, and so on).
4. The layout named in `settings.json` for that template, usually `layouts/master.njk`, is then rendered. The output of step 3 is passed into it as `templateContent`.
5. The resulting HTML is returned to the visitor.

Two things follow from this that surprise people coming from other template systems:

* Templates contain the page **body only**. The `<html>` document lives in the layout.
* The layout is rendered around the template rather than inherited from it. It receives the finished body as `templateContent` and decides where to place it.

<Note>
  Themes run server-side. Anything you put in a theme file, including comments and unused settings, can end up in the response or in a file that is publicly served. Never put API keys, webhook secrets, or other credentials in a theme.
</Note>

## Anatomy

```
my-theme/
  layouts/       Full HTML documents. Usually just master.njk
  templates/     One file per page type: shop.njk, product.njk, cart.njk, ...
  components/    Editor-addable sections: hero.njk, products.njk, footer.njk, ...
  snippets/      Reusable partials: product-card.njk, meta-tags.njk, ...
  assets/        style.css, built.css, script.js, custom.css, custom.js
  schema.json    Declares configurable settings and components
  settings.json  The merchant's actual values and page composition
  tailwind.config.js
```

See [Theme Structure](/developers/theme-structure) for what belongs in each folder.

## Ways to edit a theme

<CardGroup cols={3}>
  <Card title="Theme CLI" icon="terminal" href="/developers/theme-cli">
    Recommended. Edit files locally in your own editor, with live preview, auto-sync, and Tailwind builds.
  </Card>

  <Card title="Code editor" icon="file-code">
    Built into the dashboard. Edit any theme file in the browser. Good for quick fixes without a local setup.
  </Card>

  <Card title="Visual editor" icon="wand-magic-sparkles">
    Add, reorder, and configure components without code. Driven entirely by your `schema.json`.
  </Card>
</CardGroup>

The three are views onto the same files. A component you add in `components/` with a matching entry in `schema.json` immediately becomes addable in the visual editor.

## Official themes

New themes are usually created from an official theme, then customized. Pass the template ID to the CLI with `--template`:

| ID | Name | Notes |
| - | - | - |
| `canvas` | Canvas | Default. The most current architecture, recommended for new work. |
| `marble` | Marble | Same architecture as Canvas, with a more advanced feature set. A \$49.99 one-time purchase, or free on the Scale plan. |
| `main` | Alpha | Long-standing general purpose theme. |
| `blue` | Blue | Long-standing general purpose theme. |
| `pro` | Pro | Bootstrap-based rather than Tailwind. |

<Tip>
  Start from `canvas` unless you have a reason not to. The examples throughout these docs come from it.
</Tip>

## Theme updates

When you update a theme from its official base, the official files overwrite yours. These are preserved:

* `settings.json`
* `assets/custom.css`
* `assets/custom.js`
* `templates/custom-page.njk`

New templates added by the official theme are merged into your `settings.json`, so newly supported pages appear after an update. Existing template settings are left alone.

<Warning>
  Anything you changed outside those four files is replaced on update. Put custom styling in `assets/custom.css` and custom behavior in `assets/custom.js`, or keep your theme in version control and reapply your changes after updating.
</Warning>

New settings added by an official update are not backfilled into an existing `settings.json`. Always read settings with a fallback, as described in [Settings and Schema](/developers/theme-settings).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.