Build a Commera theme

A Commera theme controls how your storefront looks. It is a Shop Theme record plus a folder of Jinja templates, CSS and scripts in a Frappe app. You keep the theme in your own app, so Commera upgrades do not overwrite your work.

How a URL becomes a page

flowchart TD
    A[Shopper opens /en/products/blue-shirt] --> B{A Themed Routes row matches?}
    B -->|yes| C[Template Path, for example pages/products/details.html]
    B -->|no, and Enable Dynamic Pages is on| D[pages/en/products/blue-shirt.html]
    B -->|no| G[Commera core page serves the URL]
    C --> E{Active theme has the file?}
    D --> E
    E -->|yes| H[Render it from the active theme]
    E -->|no| F{A parent theme has the file?}
    F -->|yes| I[Render it from the parent theme]
    F -->|no| G

Commera matches the path against the Themed Routes table in Shop Theme Settings. The row gives a template path, such as pages/products/details.html.
Commera looks for that file in the active theme. If the file is not there, it looks in the parent theme, then in the parent's parent.
The first theme that has the file renders the page. Its .py controller, if any, adds data to the page.
If no theme in the chain has the file, Commera's core page serves the URL.

The same lookup applies to every components/... file that a page includes or imports, and to every asset. A theme only needs the files that it changes.

The bundled themes

Theme	What it is	Use it as
Shop Base Theme	The foundation. It has no pages. It ships the HTML skeleton, `components/base.html`, and the brand logo macros.	The parent of a new theme that you design from zero
Shop Default Theme	A Tailwind CSS storefront	A reference for a Tailwind build setup only. Its `components/base.html` is an older copy. Do not use it as a model for your layout.
Summer Theme	A full storefront in plain CSS. A new Commera site uses it.	The parent of a theme that changes only a few parts

Always set a parent theme

Set Parent Theme to Shop Base Theme, or to a theme that inherits from it, such as Summer Theme. Do not make a theme without a parent.

Shop Base Theme gives every page these parts:

The HTML skeleton, with the lang and dir attributes for English and Arabic
The SEO meta tags and the JSON-LD structured data
The analytics tags that the merchant sets up
The favicon and the merchant's colours, as --ls-* CSS variables
Alpine.js, and the cart, wishlist, translation and toast stores that the storefront scripts use

Your layout extends components/base.html and fills its blocks. Do not copy base.html into your theme. A copy stops getting Commera's fixes to SEO, analytics and the cart.

What you'll build

Acme: a new theme in plain CSS, with Shop Base Theme as its parent. It has its own layout, home page and product page.
Acme Catalog: a child of Summer Theme that hides every price. It changes three templates, adds one controller, and inherits the rest.

Both themes live in one app, acme_theme.

Requirements

A Frappe bench with Commera installed on a site
Developer mode on for the site. Commera makes the theme folders and writes the theme record to your app only in developer mode:
```
bench --site your.site set-config developer_mode 1
```
A Desk user with the System Manager role

Next steps

Step 1: Create the theme
Architecture: the folder layout and the fallback order
Routes and pages: which URL loads which file