Theme Structure Overview

A Qumra theme is a collection of files that define the look and functionality of a storefront. This guide provides an overview of the theme structure.

Folder Structure

my-theme/
├── .qumra/
│   └── qumra.config.json        # Theme metadata (id, version, name)
├── assets/
│   ├── style.css                # Global styles
│   ├── main.js                  # Main JavaScript
│   ├── alpine.config.js         # Alpine.js configuration
│   └── alpine.ecommerce.js      # E-commerce Alpine components
├── layouts/
│   └── layout.njk               # Main HTML shell
├── locales/
│   ├── ar.json                  # Arabic translations
│   ├── en.json                  # English translations
│   └── fr.json                  # French translations
├── pages/
│   ├── index.json               # Homepage
│   ├── product.json             # Product page
│   ├── collection.json          # Collection page
│   ├── cart.json                # Cart page
│   └── ...                      # Other pages
├── settings/
│   ├── settings-schema.json     # Settings definition (groups + fields)
│   ├── settings-data.json       # Settings values
│   └── templates-settings.json  # Template rendering order
├── templates/
│   ├── header.json              # Header widgets
│   ├── footer.json              # Footer widgets
│   └── global.json              # Global widgets (WhatsApp, mobile nav)
├── ui/
│   ├── button.njk               # Button component
│   ├── product-card.njk         # Product card component
│   └── ...                      # Other UI components
└── widgets/
    ├── hero-slider/
    │   ├── schema.json          # Widget settings + blocks
    │   └── widget.njk           # Widget template
    ├── product-details/
    ├── testimonials/
    └── ...                      # Other widgets

---

Detailed Guides

Folder	Description
assets	Frontend files (CSS, JS, media)
layouts	Base Nunjucks layouts
locales	Translations and {% translate %} tag
pages	Page definitions and widget ordering
settings	Theme settings schema and values
templates	Header, footer, global widget groups
ui	Reusable UI components
widgets	Page sections (schema + template)

---

Quick Examples

Including Assets

<link rel="stylesheet" href="{{ 'style.css' | assets }}">
<script src="{{ 'main.js' | assets }}" defer></script>

Using UI Components

{% ui "button.njk", { text: "Buy now", variant: "primary" } %}
{% ui "product-card.njk", product=product %}

Including Templates

{% template "header" %}
{% content " " %}
{% template "footer" %}
{% template "global" %}

Page JSON with Widgets

{
  "layout": "layout",
  "title": "Homepage",
  "widgets": [
    {
      "name": "hero-slider",
      "widget": "hero-slider",
      "settings": {
        "autoplay": true,
        "speed": 5
      },
      "blocks": [
        {
          "block": "slide",
          "name": "Welcome Slide",
          "settings": {
            "title": "Welcome to Our Store",
            "buttonText": "Shop Now"
          }
        }
      ]
    }
  ]
}

---

Widget Schema & Field Types

Each widget has a schema.json that defines its settings and blocks:

{
  "name": "Hero Slider",
  "settings": {
    "autoplay": { "type": "boolean", "label": "Autoplay", "default": true },
    "speed": { "type": "number", "label": "Speed", "default": 5 }
  },
  "blocks": {
    "slide": {
      "name": "Slide",
      "settings": {
        "title": { "type": "string", "label": "Title" },
        "image": { "type": "media", "label": "Image" }
      }
    }
  }
}

View All Field Types →