Generate Widget

Generate a new widget with schema and template files for your Qumra theme.

Usage

qumra gen widget <widget-name>

Parameters

• widget-name (required): The name of the widget to generate. Must be lowercase with only letters, numbers, and dashes.

Interactive Steps

1. Widget Name: Provide the widget name as an argument
2. Page Selection: Choose which page to add the widget to
3. Confirmation: Widget is created and added to the selected page

What Gets Created

The command creates a widget folder with two files:

widgets/<widget-name>/
├── schema.json    # Widget settings definition
└── widget.njk     # Widget template (Nunjucks)

Example

$ qumra gen widget product-card

? Select the page to add the widget to:
❯ index.json
  product.json
  collection.json
  cart.json

✅ Widget 'product-card' created and added to 'index.json' successfully.

Generated Files

schema.json:

{
  "name": "Product Card",
  "settings": {
    "title": {
      "type": "string",
      "label": "Title",
      "default": ""
    }
  }
}

widget.njk:

<div class="widget product-card">
  <h2>{{ widget.data.title }}</h2>
  <!-- Your widget content here -->
</div>

Requirements

• Must be inside a Qumra theme directory (with .qumra/qumra.config.json)
• Widget name must be lowercase with only letters, numbers, and dashes
• Widget must not already exist

Naming Convention

Valid	Invalid
product-card	ProductCard
hero-slider	hero_slider
faq-section	FAQ Section

---

Tips

Best Practices

• Use descriptive, lowercase names with dashes
• Each widget should serve a single purpose
• Define all settings in schema.json before building the template
• Use blocks for repeatable content (slides, items, FAQs)

After Generation

1. Edit schema.json to define your widget settings
2. Build your HTML template in widget.njk
3. Access settings using {{ widget.data.settingName }}
4. Test with qumra theme dev

---

Troubleshooting

Error: "Not in a theme directory"

Make sure you're inside a Qumra theme folder with .qumra/qumra.config.json.

Error: "Widget name is required"

Provide the widget name: qumra gen widget <name>

Error: "Widget already exists"

Use a different name or delete the existing widget folder first.

Error: "Invalid widget name"

Widget names must be lowercase with only letters, numbers, and dashes.