Skip to main content

​
What a theme is

A SellAuth theme is a folder of 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.

Quickstart

Create, pull, and edit your first theme in a few minutes.

Theme Structure

Folders, template names, and how routes map to files.

​
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.
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.

​
Anatomy

See Theme Structure for what belongs in each folder.

​
Ways to edit a theme

Theme CLI

Recommended. Edit files locally in your own editor, with live preview, auto-sync, and Tailwind builds.

Code editor

Built into the dashboard. Edit any theme file in the browser. Good for quick fixes without a local setup.

Visual editor

Add, reorder, and configure components without code. Driven entirely by your schema.json.
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:
Start from canvas unless you have a reason not to. The examples throughout these docs come from it.

​
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.
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.
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.