Shopify theme app extensions: stop your app from editing theme code
From the work/ 12 min read
Shopify theme app extensions in practice: app blocks versus app embeds, a full extension built with Shopify CLI, the end of script tags and the App Store rules.
- Shopify
- Shopify apps
- Themes
In this article (9)
Shopify theme app extensions are how your app adds content or scripts to a store without editing theme code. You ship app blocks and app embeds, the merchant turns them on in the theme editor, and Shopify removes them when the app is uninstalled. The App Store requires them.
Below is a complete example extension (a low-stock notice and a help bubble), how to generate it with Shopify CLI, what to do with the script tags your app already installed, and the current requirements. We ran the extension through shopify theme check locally, without connecting it to any store.
The problem with code that stays behind
For years, integrating an app with a store meant one of two things: write a snippet into snippets/ through the Asset API and edit theme.liquid or the product template to render it, or register a script tag that loaded remote JavaScript on every page. Shopify's migration guide has a name for the result: ghost code. Uninstalling the app often leaves those edits in the theme, which causes quality and performance issues and takes the theme off its upgrade path. Per the online store integration docs, when someone removes that code by hand, even one extra line break or space is enough to break the upgrade path.
If you have dealt with this as a merchant, the article on measuring the performance impact of Shopify apps covers finding and cleaning what apps leave behind. This one is about the other side: what the person building the app has to do so nothing is left.
Script tags also have an end date. Per Shopify's storefront script tags page, read on November 19, 2026:
- Since October 1, 2026 you cannot create or update script tags:
scriptTagCreateandscriptTagUpdatereturn a permission error on every API version. Pinning an older version does not defer it. - On the Order status page they stopped working on August 26, 2026.
- On March 1, 2027 Shopify stops injecting them into storefront pages. Reading and deleting keep working until then.
Scroll the figure sideways to see all of it
App blocks vs app embed blocks
A theme app extension is a bundle of app blocks, app embed blocks, assets and snippets. The target value in the schema decides which kind of block you have, per the configuration docs:
| App block | App embed | |
|---|---|---|
target | content (section is the legacy value and still works) | head, compliance_head or body |
| Where it renders | Inside a section, wherever the merchant puts it | Before </head> or </body> |
| Themes | Online Store 2.0 only: JSON templates and sections that accept @app blocks | Vintage and Online Store 2.0 |
| Data | Can point at dynamic sources with autofill | Only the page's global Liquid scope |
| After install | Not in the theme until the merchant adds it | Deactivated until the merchant turns it on |
| Good for | Reviews, star ratings, notices on the product page | Chat bubbles, floating badges, pixels, meta tags |
The short rule: if your app draws something inside the page, use an app block; if it floats on top, has no UI or only loads JavaScript, use an app embed. compliance_head loads before the others, and Shopify asks you to use it only when you must, for a cookie banner for example. Neither kind renders on checkout pages; other extensions cover those.
Scroll the figure sideways to see all of it
Build the extension with Shopify CLI
From your app folder, the getting started guide uses an interactive command. With flags it looks like this (we read the template id from the Shopify CLI 3.88.1 source):
shopify app generate extension --template theme_app_extension --name stock-badge
extensions/stock-badge
├── assets/ stock-badge.css, help-bubble.css, help-bubble.js
├── blocks/ stock-badge.liquid, help-bubble.liquid
├── snippets/
├── locales/ en.default.json, es.json, en.default.schema.json, es.schema.json
└── shopify.extension.toml
--template theme_app_extensionpicks the type; leave it out and the CLI asks.--namenames the folder and the extension.assets/holds CSS, JavaScript and images, which Shopify serves from its CDN.blocks/holds one Liquid file per app block or app embed. The file name is the block's handle.snippets/holds Liquid shared between blocks;locales/holds translations for the storefront and for the editor.shopify.extension.tomlonly needsnameandtype = "theme": the schemas drive the behavior.
The generated template ships a star rating example that needs a demo.avg_rating metafield; we replaced it with these two blocks. The first is the app block for the low-stock notice:
{%- liquid
assign badge_product = block.settings.product
assign variant = badge_product.selected_or_first_available_variant
assign quantity = variant.inventory_quantity
-%}
{%- if variant.inventory_management == 'shopify' and quantity > 0 and quantity <= block.settings.threshold -%}
<p class="stock-badge" style="--stock-badge-color: {{ block.settings.color }}">
{{ 'stock_badge.low_stock' | t: quantity: quantity }}
</p>
{%- endif -%}
{% schema %}
{
"name": "t:blocks.stock_badge.name",
"target": "content",
"stylesheet": "stock-badge.css",
"enabled_on": { "templates": ["product"] },
"settings": [
{ "type": "product", "id": "product", "label": "t:blocks.stock_badge.product", "autofill": true },
{ "type": "range", "id": "threshold", "label": "t:blocks.stock_badge.threshold", "min": 1, "max": 20, "step": 1, "default": 5 },
{ "type": "color", "id": "color", "label": "t:blocks.stock_badge.color", "default": "#b42318" }
]
}
{% endschema %}
- The
liquidtag reads the product from theproductsetting. Because that setting hasautofill, Shopify fills it with the product of the section the block is added to. selected_or_first_available_variantis the variant selected in the URL, or the first available one.- The condition checks
inventory_management == 'shopify'because, per the Liquid reference, when inventory is not trackedinventory_quantityreturns the number sold, and the notice would be wrong. - The text comes from
locales/through thetfilter, so the store shows it in its own language. The color goes in as a CSS variable. "target": "content"makes it an app block;enabled_onlimits it to the product template.stylesheetloadsassets/stock-badge.cssonly on pages where the block is present.- The
t:labels come fromen.default.schema.jsonandes.schema.json, so the editor shows the settings in the merchant's language.
The second is the app embed. Its schema is the part that matters:
{% schema %}
{
"name": "t:blocks.help_bubble.name",
"target": "body",
"javascript": "help-bubble.js",
"stylesheet": "help-bubble.css",
"enabled_on": { "templates": ["product", "collection"] },
"settings": [
{ "type": "url", "id": "link", "label": "t:blocks.help_bubble.link" },
{ "type": "text", "id": "label", "label": "t:blocks.help_bubble.label", "default": "Help" }
]
}
{% endschema %}
"target": "body"makes it an app embed: Shopify injects its HTML before</body>.javascriptloadsassets/help-bubble.jsonly when the embed is active on that page. If several blocks reference the same file, it is included once.enabled_onlimits the embed to product and collection pages. Shopify calls this out as the advantage over a script tag, which could not load on specific pages only.- The settings are the minimum: a link and a label. The UX guidelines ask you not to clutter the app embeds panel.
We validated it with shopify theme check --path extensions/stock-badge: "6 files inspected with no offenses found". On a broken copy it flagged the missing CSS file, the missing translation key and an unclosed tag. It did not flag a made-up target, so check that value yourself. To see the extension on a dev store, run shopify app dev (the preview only works in Chrome); to ship it, shopify app deploy, which creates an app version. shopify app build runs Theme Check and the size limits before you deploy:
| Limit | Value | Type |
|---|---|---|
| All files in the extension | 10 MB | Enforced |
| Blocks | 30 | Enforced |
| Locale files / size of each | 100 / 15 KB | Enforced |
| Liquid across all files | 100 KB | Enforced |
| Compressed CSS referenced in the schema | 100 KB | Suggested |
| Compressed JS referenced in the schema | 10 KB | Suggested |
What the merchant gets
- An untouched theme. The app edits no files, so the theme stays on its upgrade path.
- Control over placement. They add, remove and reorder app blocks from the Apps section of the editor, turn embeds on or off under App embeds, and preview before saving.
- An off switch that does not need you. The embed shows up in the editor, where the merchant can see your app is running and turn it off.
- A clean uninstall. The UX guidelines say that when an app is uninstalled, its blocks are removed from the theme automatically and entirely.
- Less weight. Assets come from Shopify's CDN and scripts load only on the templates you pick.
A block can also show content the merchant edits in the admin: with the $app: reserved prefixes it reads your app's metafields and metaobjects without hard-coding your app ID. For that pattern, see metaobjects for editable content. And if your script recalculated prices or discounts in the cart with JavaScript, that logic does not belong in an embed: it belongs in Shopify Functions.
One catch: an app embed is turned on per theme. If the store publishes a different theme, your embed is not active there and has to be turned on again.
Scroll the figure sideways to see all of it
How to clean up your app's old code
If your app is already installed through script tags or through snippets written with the Asset API, the migration has an order. Embeds start deactivated and your app cannot turn them on for the merchant, so if you delete the script tag first, the feature disappears until someone activates the embed:
- Ship the extension with an app embed that does what the script tag did.
- Send the merchant into the editor with the embed already on, using a deep link:
https://<store>.myshopify.com/admin/themes/current/editor?context=apps&template=product&activateAppId={api_key}/help-bubble, whereapi_keyis theclient_idin yourshopify.app.tomlandhelp-bubbleis the block's file name. - Confirm it is active:
app.extensions()from your app in the admin returnsactiveoravailableper block; from your backend, read the published theme'sconfig/settings_data.jsonwith theread_themesscope. - Delete the script tag. If both run, the script loads twice: duplicate analytics events or the UI drawn twice.
To find and delete your app's script tags, with the token it already holds for that store:
query AppScriptTags {
scriptTags(first: 50) {
nodes { id src displayScope createdAt }
}
}
mutation DeleteScriptTag($id: ID!) {
scriptTagDelete(id: $id) {
deletedScriptTagId
userErrors { field message }
}
}
scriptTagsreturns only your app's script tags, up to 50 per page.srctells you which file each one loads anddisplayScopewhere it runs; if it isorder_statusorall, that part has already stopped working.scriptTagDeletetakes theidand needs thewrite_script_tagsscope.userErrorscomes back empty on success; check it before you mark the store as migrated.
What the Asset API wrote into the theme does not leave on its own. The migration guide says that if the published theme supports app blocks, your app should skip every POST to Asset and ScriptTag, and the integration docs ask you to give merchants instructions to remove that code completely. Put them on your onboarding screen, next to the deep link; if you build it with Polaris, they sit inside the admin like the rest of your app. One exception: custom apps created in the admin cannot use extensions at all; for those, the script goes into a custom Liquid block in the theme.
Shopify App Store requirements for theme app extensions
Section 5.1 of the App Store requirements, read on November 19, 2026, says themes are modified only through theme app extensions:
- 5.1.1. If your app modifies the theme, it must use theme app extensions. Neither you nor the merchant should make code changes to the theme.
- 5.1.2. The widget must display properly and without errors in the theme editor and the online store.
- 5.1.3. The app must include detailed instructions for installing its app embeds and app blocks; Shopify strongly recommends a deep link.
The UX guidelines add two things reviewers look at: the listing should say whether the app needs an Online Store 2.0 theme, and each block name should stay under 25 characters and leave out the app's name, which the editor already shows under it.
Common mistakes
- Deleting the script tag before the embed is active. The store loses the feature until the merchant opens the editor.
- Leaving both running. The script runs twice and events double.
- Using
"target": "section"on new blocks. It works, but it is the legacy value: usecontent. - An app block for something that floats. A chat or a floating badge is an embed; an app block needs an Online Store 2.0 theme.
- Expecting dynamic sources in an embed. It only sees the global Liquid scope; for the section's product, use an app block with
autofill. - Reading
inventory_quantitywithout checking tracking. Untracked, it returns the number sold. - Forgetting the embed is per theme. When the store switches themes, check it again.
Frequently asked questions
Do theme app extensions work on vintage themes?
App embeds do, because they do not rely on sections or JSON templates. App blocks do not: they need JSON templates and sections that accept @app blocks.
What happens to my extension when the merchant uninstalls the app?
Per Shopify's UX guidelines, the app's blocks are removed from the theme automatically and entirely. Anything your app wrote with the Asset API is not covered by that.
Can I keep using script tags?
Since October 1, 2026 you cannot create or update any, and on March 1, 2027 they stop loading on storefronts. To load JavaScript, use an app embed; if you only collect analytics, a web pixel.
Do I need to list on the App Store to use them?
No. Any app created with Shopify CLI or the Dev Dashboard can have extensions, custom apps included. The exception is custom apps created directly in the Shopify admin.
Checklist
- The app does not write to the theme through the Asset API and creates no script tags.
- In-page content is an app block with
"target": "content"; floating or UI-less code is an app embed. - Product app blocks use
autofillandenabled_on. - JavaScript lives in
assets/and loads throughjavascriptonly on the templates that need it. - Text comes from
locales/, for the storefront and the editor. shopify theme checkpasses and the extension fits the limits.- The onboarding screen explains how to turn the blocks on and includes the deep link.
- Script tags are deleted only after the embed is confirmed active.
An app that leaves the theme alone is also easier to remove, which matters when a merchant weighs building a custom app against installing one from the store.
Saw this on Instagram? Every Reel guide is at ecomlabs.dev/guides.
Written by

Published November 19, 2026 · updated November 20, 2026