How themes work

A theme is everything your storefront looks like: its layout, its sections, its CSS and JavaScript. Sworen themes are written in Liqx, a template language that looks like HTML with JavaScript-style expressions. See Liqx syntax.

Sworen ships with themes you can use and copy: Cein and Flora are full-featured, and Default is a deliberately minimal reference. You’ll find them on your server under apps/storefront/.

The files in a theme

my-theme/
├── theme.json                  required: name, version, author, description, optional slug
├── layout/theme.liqx           required: the HTML shell around every page
├── templates/*.json            which sections each page shows, in what order
├── sections/*.liqx             the building blocks a merchant arranges
├── sections/<group>.json       section groups, such as everything above the header
├── blocks/*.liqx               smaller pieces placed inside sections
├── snippets/*.liqx             reusable components (<ProductCard />…)
├── config/settings_schema.json the theme's own settings
├── config/settings_data.json   their current values
├── assets/                     CSS, JavaScript, images, fonts
└── locales/                    translations for the `t` filter

The store accepts a theme only if it follows these rules:

• Root files: theme.json, and optionally a readme and a license (.md or .txt).
• Folders: only assets, blocks, config, layout, locales, sections, snippets and templates.
• File types: liqx, json, css, js, map, images (png, jpg, jpeg, gif, webp, avif, svg, ico), fonts (woff, woff2, ttf, otf, eot), txt and md. Never .php.
• Size: at most 40 MB unpacked and 2,000 files.

The theme’s slug (its id in URLs and commands) is slug from theme.json, or else its name in lowercase with hyphens.

Pages and templates

Each kind of page uses one template:

Template	Page
index	Home page
product	A product (/products/{handle}), with the order form
collection	A collection (/collections/{handle})
list-collections	All collections
page	A content page (/pages/{handle})
search	Search results
cart	The cart
thanks	The thank-you page after an order
tracking	Order tracking
account-login, account-register, account	Optional customer accounts
404	Page not found

A template is a JSON file that lists sections and their order:

{
  "sections": {
    "hero": { "type": "hero", "settings": { "heading": "New collection" } },
    "products": { "type": "featured-products", "settings": { "limit": 8 } }
  },
  "order": ["hero", "products"]
}

type is the section’s file name in sections/. Merchants change these in the theme editor; you rarely edit them by hand.

Getting a theme onto your store

1. Upload it with the theme CLI (sworen push), or copy the theme folder to apps/storefront/<slug>/ on your server.
2. Activate it in the admin under Themes.
3. Customize it with Customize: the theme editor, where you add and arrange sections, change settings and preview the result.
4. Publish from the editor. Template and settings changes stay in a draft until you publish; theme files (Liqx, CSS, JavaScript) are live as soon as they are uploaded.