---
title: "Build a Commera theme"
space: "Commera"
url: "https://docs.bwh.tech/commera/build-a-theme/overview"
updated: "2026-10-08"
---

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

```mermaid
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
```

1. 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`.
2. 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.
3. The first theme that has the file renders the page. Its `.py` controller, if any, adds data to the page.
4. 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:

    ```bash
    bench --site your.site set-config developer_mode 1
    ```

- A Desk user with the System Manager role

## Next steps

- [Step 1: Create the theme](/commera/build-a-theme/create-the-theme)
- [Architecture](/commera/theme-reference/architecture): the folder layout and the fallback order
- [Routes and pages](/commera/theme-reference/routes-and-pages): which URL loads which file