Theme App Extensions

The problem this solves

So far everything has lived in the admin. But many apps need to show something to shoppers — a badge on a product, reviews, a size chart.

The tempting shortcut is to edit the merchant's theme code directly. Do not. It breaks the moment they switch or update their theme, it is hard to undo, and the App Store rejects apps that do it.

A theme app extension is the proper way: you ship small pieces of Liquid with your app, and the merchant places them using the normal theme editor.

Two kinds of block

Create one

shopify app generate extension

Choose Theme app extension and give it a name. You get a new folder:

extensions/
└── storefront-badges/
    ├── assets/                 CSS, JS, images
    ├── blocks/                 your blocks — one .liquid file each
    ├── snippets/               reusable Liquid pieces
    ├── locales/                translations
    └── shopify.extension.toml  name and type

The generated example shows product ratings, and needs a matching metafield to display anything — so if the preview is blank at first, that is expected.

An app block

Continuing the badges app from Note 14: show the product's badge on the product page.

{%- assign badge = product.metafields.custom.badge.value -%}

{%- if badge and badge.label != blank -%}
  <span
    class="product-badge"
    style="background: {{ badge.color | default: block.settings.fallback_color }};"
  >
    {{ badge.label | escape }}
  </span>
{%- endif -%}

{% schema %}
{
  "name": "Product badge",
  "target": "section",
  "enabled_on": { "templates": ["product"] },
  "stylesheet": "product-badge.css",
  "settings": [
    {
      "type": "color",
      "id": "fallback_color",
      "label": "Colour if none is set",
      "default": "#0a6b57"
    }
  ]
}
{% endschema %}

.product-badge {
  display: inline-block;
  padding: 2px 10px;
  border-radius: 999px;
  color: #fff;
  font-size: 12px;
  font-weight: 600;
}

How the pieces connect:

• The top half is Liquid — Shopify's template language. It runs on Shopify's servers when the page is built, with access to product, shop and so on.
• {% schema %} describes the block to the theme editor: its name, where it may be used, and the settings the merchant can change.
• settings become form fields in the theme editor, read back as block.settings.fallback_color.
• "stylesheet" loads a file from assets/ only on pages where the block is used.

An app embed block

For something that floats over every page instead of sitting inside a section:

<div class="help-bubble">
  <a href="{{ block.settings.link }}">{{ block.settings.label | escape }}</a>
</div>

{% schema %}
{
  "name": "Help bubble",
  "target": "body",
  "stylesheet": "help-bubble.css",
  "settings": [
    { "type": "text", "id": "label", "label": "Label", "default": "Need help?" },
    { "type": "url",  "id": "link",  "label": "Link" }
  ]
}
{% endschema %}

The only structural difference is "target": "body".

Getting your data into a block

This is the key limitation to understand: a block cannot query your database. It runs as Liquid on Shopify's servers, with no connection to your app. Your data has to reach it another way.

App-owned metafields are worth knowing. They belong to your app's installation rather than to any product, so merchants and other apps cannot edit them. Write them with metafieldsSet using your installation's id as the owner:

query { currentAppInstallation { id } }   # → gid://shopify/AppInstallation/123

Then read them in any block as app.metafields.namespace.key.

Previewing

shopify app dev

With an extension present, the CLI walks you through previewing it: it opens the theme editor, you add your block, save, and open the preview link. Changes reload as you save files.

• Choose which theme with --theme. Without it, the CLI uploads Shopify's reference theme to your dev store.
• The live preview works in Google Chrome.
• Test with real data: give a product an actual badge first.

Shipping it

shopify app deploy

That releases a new app version including the extension, and every store with your app gets the update — no per-store work.

Merchants still decide where the block goes. Adding a new block type does not place it on their storefront automatically — they add it in the theme editor.

Common problems

Checklist

• No edits to the merchant's theme files — everything ships as blocks.
• App blocks for positioned content; embeds for floating or invisible content.
• Merchant-entered text passed through escape.
• Data delivered by metafields, block settings or an app proxy.
• Setup instructions in your admin, including how to enable embeds.
• Tested on at least two different themes.
• Deployed with shopify app deploy.

Cheat sheet

# create
shopify app generate extension   → Theme app extension

# block types
"target": "section"   app block — merchant places it
"target": "body"      app embed — OFF until merchant enables it

# schema essentials
name · target · enabled_on · stylesheet · javascript · settings

# reading data
product.metafields.custom.x.value   resource data
app.metafields.ns.key               app-wide settings
block.settings.x                    merchant's choices
fetch('/apps/…')                    live data via app proxy

# ship
shopify app deploy     (a server deploy does NOT update blocks)

# always
{{ text | escape }}