---
title: "Structure"

doc_type: static
doc_category: static
doc_version: v20270301
source_url:
  html: 'https://developer.shopline.com/docs/online-store-3-0-themes/integrate-apps-with-themes/theme-app-extension/structure'
  md: 'https://developer.shopline.com/docs/online-store-3-0-themes/integrate-apps-with-themes/theme-app-extension/structure.md'
---
# Structure
Learn about the structure of a theme app extension and how to configure it. 

---


## Directory structure{#wjXWo}
The standard directory structure for a theme app extension is as follows:

```plain
└── theme-app-extension
    ├── blocks
    │   ├── app-block.html
    │   ├── app-embed-block.html
    │   ├── conditional-app-block.html
    │   └── ...
    ├── components
    │   ├── logo-icon.html
    │   └── ...
    ├── i18n
    │   ├── en.json
    │   ├── en.schema.json
    │   ├── zh-hans-cn.json
    │   ├── zh-hans-cn.schema.json
    │   ├── zh-hant-tw.json
    │   ├── zh-hant-tw.schema.json
    │   └── ...
    ├── public
    │   ├── app-block.css
    │   ├── app-block.js
    │   ├── app-embed-block.css
    │   ├── app-embed-block.js
    │   └── ...
    └── .shopline-cli.yml
```

Descriptions for different directories and files are as follows: 

| **Directory or file** | **Description** |
| --- | --- |
| blocks | HTML files for [App Blocks](#KOCjB) and [App Embed Blocks](#SUKRO). |
| components | Snippets of code for the theme app extension that can be referenced and reused within App Blocks and App Embed Blocks. |
| i18n | JSON files for multi-language support, storing translations for merchants and customers. These are used similarly to [theme locale files](https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/i-18-n.md). |
| public | CSS, JavaScript, and other static resources. They can be included using the `javascript` and `stylesheet` properties in the [schema](#f7tyv), or with the [asset_url](https://developer.shopline.com/docs/sline/filter/asset-url.md) filter. |
| .shopline-cli.yml  | Configuration file for the theme app extension. |


---


## App Block{#KOCjB}
App Blocks allow merchants to add blocks from the app into theme [sections](https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/sections.md). 

By default, App Blocks are not automatically added after installing an app. Merchants need to add App Blocks using the theme editor manually.

The following example creates a simple `<span>` element with a `style` attribute. For detailed configuration in the `schema` tag within the example, refer to [Schema](#f7tyv). 

```json
<span style="color: {{ block.settings.color }}">
  App Block
</span>

{{#schema}}
  {
    "name": "App Block",
    "target": "section",
    "stylesheet": ["public/app.css"],
    "javascript": ["public/app.js"],
    "settings": [
        {
          "label": "Color",
          "id": "color",
          "type": "color",
          "default": "#000000"
        }
    ]
  }
{{/schema}}
```

The following shows examples of adding an App Block within a theme section and an independent App Block in the theme. 

| **App Block in a theme section** | **An independent App Block** |
| --- | --- |
| ![](https://s2cdn.myshopline.com/slfs/op-new/175084040162889/1746601177865-e73485ac-29b4-4c2d-922d-2e14b0409fae.png) | ![](https://s2cdn.myshopline.com/slfs/op-new/175084041940640/1746601544128-1ff34264-c6da-47cb-9eb1-76322eb173cd.png) |


App Blocks are flexible, allowing merchants to add, remove, and sort them at the section level in the theme using a visual editor.


---


## App Embed Block{#SUKRO}
App Embed Blocks enable merchants to add UI-less features or global floating elements on a page from the app into the theme. They are suitable for the following types of apps:

+ Apps that provide floating elements on the page, such as customer service chat apps and announcement notification apps.
+ Apps that add SEO meta tags, analytics, or custom forms.

You can set the `target` property in the [schema](#f7tyv) to either `head` or `body` to determine where the App Embed Block is injected. By default, App Embed Blocks are not automatically activated upon installation. Merchants need to activate them from **Theme settings** > **App embeds** in the theme editor.

The following example demonstrates an App Embed Block being inserted at the bottom of the `<body>`, rendering a button that floats at the bottom of the page.

```html
<div style="position: fixed; bottom: 0; right: 0">
  <img src="{{ `comment.jpg` | asset_url() }}" />
</div>

{{#schema}}
{
  "name": "App Embed Block",
  "target": "body",
  "settings": []
}
{{/schema}}
```

The following shows an example of the floating button rendered on the page.

![](https://s2cdn.myshopline.com/slfs/op-new/175084048354265/1746604849862-9e90ffb3-5040-472f-9690-ef16c131f1ac.png)


---


## Schema{#f7tyv}
The schema for App Blocks and App Embed Blocks is similar to the [theme section schema](https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/sections.md#Fc76g)
 and supports the following attributes. Some attributes are unique to App Blocks and App Embed Blocks. 

<table>
  <tr>
    <th>Attribute name</th>
    <th>Type</th>
    <th>Required or not</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>name</td>
    <td>string</td>
    <td>Yes</td>
    <td>Title of the App Block or App Embed Block in the theme editor. Recommended to be within 25 characters to fit the theme editor sidebar.</td>
  </tr>
  <tr>
    <td>target</td>
    <td>string</td>
    <td>Yes</td>
    <td>
      Position on the page where the App Block or App Embed Block is rendered.<br/>
        
      App Blocks support the value `section`, indicating rendering in the theme section.<br/>
        
      App Embed Blocks support the following values:<br/>
    - `head`: indicates in the `<head>` tag of the page.<br/>
    - `body`: indicates in the `<body>` tag of the page.
    </td>
  </tr>
  <tr>
    <td>stylesheet</td>
    <td>array</td>
    <td>No</td>
    <td>CSS files to load from the `public` directory.<br/>
    The path must include the `public` prefix, for example, `public/app.css`.</td>
  </tr>
  <tr>
    <td>rtl_stylesheet</td>
    <td>array</td>
    <td>No</td>
    <td>
      RTL CSS files to load from the `public` directory.<br/>
      The path must include the `public` prefix, for example, `public/rtl-app.css`.
      > **CAUTION**
>
> This attribute only takes effect when the language is set to `ar` [(Arabic)](https://developer.shopline.com/docs/online-store-3-0-themes/best-practice/arabic.md). If `rtl_stylesheet` is not provided for `ar`, the `stylesheet` attribute will be used as a fallback.
      </td>
  </tr>
  <tr>
    <td>javascript</td>
    <td>array</td>
    <td>No</td>
    <td>JavaScript files to load from the `public` directory.<br/>
    The path must include the `public` prefix, for example, `public/app.js`.<br/>
    The injected `<script>` tag will automatically include the `defer` attribute.</td>
  </tr>
   <tr>
    <td>resource</td>
    <td>object</td>
    <td>No</td>
    <td>
      An object for integrated resource management, providing more granular control over resource loading.<br/>
      If this attribute is defined, the `stylesheet`, `rtl_stylesheet`, and `javascript` attributes will be ignored.<br/>
      Example:<br/>
        ```json
      {   
          "resource": {     
            "css": [       
              {
                "src": "public/app.css"       
              }     
            ],     
            "rtl_css": [       
              {         
                "src": "public/rtl_app.css"       
              }     
            ],     
            "js": [       
              {         
                "src": "public/app.js"       
              }     
            ]   
          } 
        } 
        ```  
        </td>
  </tr>
  <tr>
    <td>resource.css</td>
    <td>array</td>
    <td>No</td>
    <td>
      Array of CSS resource configurations.<br/> 
      Attributes:<br/>
    - `src` (required): The CSS file to load from the `public` directory.<br/>
    - `preload` (optional): Whether to preload the resource.<br/>
       - `true`: Preloads the resource.
       - `false`  (default): Does not preload the resource.
    - `position` (optional): Resource injection position.<br/>
       - `"header"` (default): Injected within `{{#content "header" /}}`.
       - `"footer"`: Injected within `{{#content "footer" /}}`.
    </td>
  </tr>
  <tr>
    <td>resource.rtl_css</td>
    <td>array</td>
    <td>No</td>
    <td>
      Array of RTL CSS resource configurations.<br/> 
      Attributes:<br/>
    - `src` (required): The CSS file to load from the `public` directory.<br/>
    - `preload` (optional): Whether to preload the resource.<br/>
       - `true`: Preloads the resource.
       - `false` (default): Does not preload the resource.
    - `position` (optional): Resource injection position.<br/>
       - `"header"` (default): Injected within `{{#content "header" /}}`.
       - `"footer"`: Injected within `{{#content "footer" /}}`.
    > **CAUTION**
>
> This attribute only takes effect when the language is set to `ar` [(Arabic)](https://developer.shopline.com/docs/online-store-3-0-themes/best-practice/arabic.md). If `resource.rtl_css` is not provided for `ar`, the `resource.css` attribute will be used as a fallback.
      </td>
  </tr>
  <tr>
    <td>resource.js</td>
    <td>array</td>
    <td>No</td>
    <td>
      Array of JavaScript resource configurations.<br/> 
      Attributes:<br/>
    - `src` (required): The JavaScript file to load from the `public` directory.<br/>
    - `preload` (optional): Whether to preload the resource.<br/>
       - `true`: Preloads the resource.
       - `false` (default): Does not preload the resource.
    - `position` (optional): Resource injection position.<br/>
       - `"header"` (default): Injected within `{{#content "header" /}}`.
       - `"footer"`: Injected within `{{#content "footer" /}}`.
    - `loadStrategy` (optional): Resource loading strategy.<br/>
       - `"sync"`: Synchronous loading
       - `"async"`: Asynchronous loading
       - `"defer"` (default): Deferred execution
    </td>
  </tr>
  <tr>
    <td>templates</td>
    <td>array</td>
    <td>No</td>
    <td>
      <a href="https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/templates/">Templates</a> where the App Block or App Embed Block can be injected. Defaults to all pages if not set.<br/>
      Valid values are:<br/>
      - `index`
      - `collections_all`
      - `collection`
      - `product`
      - `cart`
      - `blog`
      - `article`
      - `404`
      - `search`
      - `page`
      - `policy`
      - `password`
      - `gift_card`
      - `customers/login`
      - `customers/register`
      - `customers/account`
      - `customers/addresses`
      - `customers/orders`
      - `customers/order`
      - `customers/activate_account`
      - `customers/forgot_password`
      - `customers/company`
    </td>
  </tr>
  <tr>
    <td>class</td>
    <td>string</td>
    <td>No</td>
    <td>
      Additional CSS classes to include in the wrapper element, similar to the `class` attribute in <a href="https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/sections#EcWCY">theme sections</a>.<br/>
      The theme app extension includes the `shopline-block` class by default.<br/>
      > **CAUTION**
>
> This attribute is not applicable when the App Embed Block's target value is `head`.
    </td>
  </tr>
  <tr>
    <td>tag</td>
    <td>string</td>
    <td>No</td>
    <td>
      Tag used to wrap the block output, defaults to `div`.<br/>
      Valid values are:<br/>
     - `article`
      - `aside`
      - `div` (default)
      - `footer`
      - `header`
      - `section`
     > **CAUTION**
>
> • App blocks do not support the configuration of this attribute.<br/>
>       • This attribute is not applicable when the App Embed Block's target value is `head`.
    </td>
  </tr>
  <tr>
    <td>settings</td>
    <td>array</td>
    <td>No</td>
    <td>
      Configuration options for the App Block or App Embed Block. For configuration details, refer to <a href="https://developer.shopline.com/docs/online-store-3-0-themes/theme-structure/sections">settings in sections</a>.
    </td>
  </tr>
  <tr>
    <td>limit</td>
    <td>integer</td>
    <td>No</td>
    <td>Limit on the number of App Blocks or App Embed Blocks that can be added into the theme section.</td>
  </tr>
</table>