---
name: joonweb-extensions
description: Guidelines for building Joonweb App Extensions, Theme Embeds, App Blocks, and .jw templates
---

# Joonweb Extensions & Theme Development Skill

Joonweb App Extensions allow apps to inject live visual blocks and scripts directly into merchant themes without modifying theme code files.

## 1. Extension Manifest (`joonweb.extension.json`)

File location: `extensions/joonweb.extension.json`

```json
{
  "name": "My AI Extension",
  "handle": "my-ai-extension",
  "type": "theme_app_extension",
  "blocks": [
    {
      "type": "announcement-bar",
      "name": "Announcement Banner",
      "target": "section",
      "src": "blocks/announcement-bar.jw"
    },
    {
      "type": "chat-widget",
      "name": "Customer Support Chat",
      "target": "body",
      "src": "blocks/chat-widget.jw"
    }
  ]
}
```

### Supported Targets:
- `section`: Visual blocks placed inside theme sections.
- `body`: Injected right before `</body>` (e.g. Chat widgets, popups).
- `head`: Injected into `<head>` (e.g. Analytics, metadata).
- `compliance_head`: Injected for legal & cookie consent banners.

## 2. `.jw` Template Format & Schema Syntax

`.jw` files combine standard HTML/Liquid markup with a mandatory `{% rules %} ... {% endrules %}` JSON schema at the end of the file.

Example (`blocks/announcement-bar.jw`):

```html
<div class="jw-banner" style="background-color: {{ section.settings.bg_color }}; color: {{ section.settings.text_color }};">
  <p class="jw-banner-text">{{ section.settings.heading }}</p>
  {% if section.settings.show_button %}
    <a href="{{ section.settings.button_link }}" class="jw-banner-btn">{{ section.settings.button_label }}</a>
  {% endif %}
</div>

{% rules %}
{
  "name": "Announcement Banner",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Banner Heading",
      "default": "Welcome to our store!"
    },
    {
      "type": "color",
      "id": "bg_color",
      "label": "Background Color",
      "default": "#4f46e5"
    },
    {
      "type": "color",
      "id": "text_color",
      "label": "Text Color",
      "default": "#ffffff"
    },
    {
      "type": "checkbox",
      "id": "show_button",
      "label": "Show CTA Button",
      "default": true
    },
    {
      "type": "url",
      "id": "button_link",
      "label": "Button Link",
      "default": "/collections/all"
    },
    {
      "type": "text",
      "id": "button_label",
      "label": "Button Label",
      "default": "Shop Now"
    }
  ]
}
{% endrules %}
```

## 3. Linter Rules for `.jw` Files
1. Must contain exactly one `{% rules %}` block and one `{% endrules %}` block.
2. The content inside `{% rules %} ... {% endrules %}` must be valid JSON.
3. Every setting object must have `type`, `id`, and `label`.