Create theme app extensions

Overview #

Theme App Extensions allow developers to build native, customizable Storefront UI components (Sections, Blocks, and Embed Scripts) using `.jw` template files and JSON rules. This step-by-step guide explains how to generate, configure, and structure a Theme App Extension using the **JoonWeb CLI**. > 🔗 **Prerequisite**: Make sure you have created your base app project first. If not, follow the [Create an App Guide](/apps/create/create-an-app).

Step 1: Open Terminal & Navigate to App Directory #

Open your terminal or command prompt and navigate directly into your existing JoonWeb app folder (where your `joonweb.app.json` manifest file is located): ```bash cd path/to/your-app ``` > ⚠️ **Directory Check**: The CLI checks if `joonweb.app.json` exists in your current folder. You cannot generate an extension outside a valid app directory.

Step 2: Run Extension Generation Command #

Execute the extension generation command: ```bash joonweb app generate extension ``` *(Alias: `joonweb app generate ext`)* ### Interactive CLI Prompts 1. **Select Extension Type**: The CLI will display the extension menu. Select **Theme App Extension** (`theme_app_extension`). ```text 🎨 Theme Extensions ────────────────── ❯ Theme App Extension - Customize store themes ``` 2. **Enter Extension Name**: Type your extension display name (e.g., `Smart Floating` or `Announcement Banner`). ```text ? Enter a name for your extension: Smart Floating ``` Once completed, the CLI registers the extension with your Partner account and scaffolds the extension directory.

Step 3: Extension Folder Structure #

After running the generation command, a new `extensions/` directory is scaffolded inside your app folder: ```text your-app/ ├── extensions/ │ └── smart-floating/ │ ├── assets/ # CSS, JavaScript, images, and static files │ ├── blocks/ # Storefront section and block .jw template files │ ├── components/ # Reusable .jw code snippets │ └── joonweb.extension.json # Extension manifest configuration └── joonweb.app.json # Main app manifest file ``` | Directory / File | Role | | - | - | | `blocks/` | Contains `.jw` UI component templates (e.g. `blocks/smart-float-block.jw`). | | `components/` | Contains reusable `.jw` code snippets included inside blocks. | | `assets/` | Static CSS stylesheets, JS scripts, and images. | | `joonweb.extension.json` | Extension configuration file linking blocks to JoonWeb Site Builder. |

Step 4: Understand joonweb.extension.json Manifest #

Inside your generated extension folder (`extensions/smart-floating/`), open `joonweb.extension.json`: ```json { "name": "Smart Floating", "version": "1.0.0", "handle": "smart-floating", "type": "theme_app_extension", "extension_key": "", "blocks": [ { "type": "app_sections", "name": "Great Float Sections", "target": "section", "src": "blocks/smart-float-block.jw" } ], "uid": "7e24ff92-9362-4765-8909-1db290511f" } ``` ### Manifest Fields Explained - **`name`**: The human-readable extension title displayed in the JoonWeb Site Builder. - **`handle`**: Unique slug identifier generated by the CLI (**DO NOT CHANGE**). - **`type`**: Fixed identifier set to `theme_app_extension` (**DO NOT CHANGE**). - **`extension_key`**: Platform registration key. - **`uid`**: Unique UUID linking the extension to your app (**DO NOT CHANGE OR REGISTRATION BREAKS**). - **`blocks`**: Array defining the UI components available in Site Builder. ### Block Properties & Types | Property | Values | Description | | - | - | - | | **`type`** | `app_sections` | Standalone section layout that merchants can add anywhere on a page. | | | `app_blocks` | Component block placed inside existing theme sections (e.g. under product price). | | | `app_embed` | Script or floating overlay injected globally. | | **`target`** | `section` | Target location for layout sections or blocks. | | | `head` / `compliance_head` / `body` | Injection targets for `app_embed` floating scripts or banners. | | **`src`** | `blocks/filename.jw` | Relative file path to your `.jw` template file. | | **`name`** | `string` | Display name of the block shown in Site Builder. | > 🚨 **Critical Rule**: Do **not** copy extension folders from other app repositories. Copying folders corrupts the extension `uid` and causes deployment failures.

📁 The .jw Template & Rules Anatomy #

Every storefront component is authored inside a `.jw` file in the `blocks/` directory (e.g., `blocks/smart-float-block.jw`). A `.jw` file combines HTML/CSS markup with a `{% rules %}` JSON schema that generates setting controls in the Site Builder: ```jw <div class="smart-float-widget" style="background-color: {{ section.settings.bg_color }}; padding: {{ section.settings.padding }}px;"> <h3 style="color: {{ section.settings.text_color }};">{{ section.settings.heading }}</h3> </div> {% rules %} { "name": "Smart Float Section", "settings": [ { "type": "text", "id": "heading", "label": "Heading Text", "default": "Special Offer!" }, { "type": "color", "id": "bg_color", "label": "Background Color", "default": "#4f46e5" }, { "type": "color", "id": "text_color", "label": "Text Color", "default": "#ffffff" }, { "type": "range", "id": "padding", "label": "Padding (px)", "min": 10, "max": 50, "step": 5, "default": 20 } ] } {% endrules %} ```

Step 5: Preview & Deploy Your Extension #

To test your extension live in your Development Store, run: ```bash joonweb app serve ``` Open your Development Store's **Site Builder**, click **Add Section** -> **Apps**, and select your extension. When ready to publish, deploy your snapshot: ```bash joonweb app deploy ```

What's Next? #

- ⚙️ **[Configure Theme App Extensions](/apps/theme-app-extensions/configure-theme-app-extensions)** — Learn Deep Linking and Asset API installation checks. - 🚀 **[Create an App Guide](/apps/create/create-an-app)** — Back to core app creation guide. - ⚙️ **[App Manifest Reference (joonweb.app.json)](/joonweb-cli/configuration/app-manifest)** — Configure app webhooks & proxy. - 🛠️ **[JoonWeb CLI Command Reference](/joonweb-cli/commands/command-reference)** — Complete CLI command options.