Shopify Theme App Extensions: The Complete Developer Guide

What are Theme App Extensions?

Theme App Extensions (TAE) let Shopify app developers add UI blocks to merchant storefronts without requiring merchants to edit theme code. They are declared in your app's extensions/ folder and rendered by Shopify's Online Store 2.0 editor.

The two building blocks are:

**App blocks** — sections that merchants drag into their theme using the Online Store Editor
**App embeds** — invisible or fixed-position elements (banners, chat widgets, scripts) that merchants toggle globally

Setting up your first Theme App Extension

shopify app generate extension --type theme_app_extension --name my-widget

This scaffolds:

extensions/
  my-widget/
    blocks/
      my_block.liquid
    snippets/
    assets/
    locales/
    shopify.extension.toml

Defining an App Block

{% comment %} blocks/my_block.liquid {% endcomment %}
<div class="my-widget" data-shop="{{ shop.permanent_domain }}">
  <!-- widget HTML -->
</div>

{% schema %}
{
  "name": "My Widget",
  "target": "section",
  "settings": [
    {
      "type": "color",
      "id": "accent_color",
      "label": "Accent colour",
      "default": "#10b981"
    }
  ]
}
{% endschema %}

Deploying

shopify app deploy

Merchants then activate your block from Online Store → Themes → Customize without touching a single line of Liquid.

Key constraints

TAE files cannot access app session tokens directly — use postMessage or Shopify App Bridge for authenticated API calls
Assets in assets/ are CDN-served but must be referenced via {{ 'my-script.js' | asset_url }}
App embeds require "target": "body" in the schema

Testing locally

shopify app dev

The CLI creates a development store tunnel so you can preview the extension in a real Shopify editor.