Skip to content

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)
  1. The problem with code that stays behind
  2. App blocks vs app embed blocks
  3. Build the extension with Shopify CLI
  4. What the merchant gets
  5. How to clean up your app's old code
  6. Shopify App Store requirements for theme app extensions
  7. Common mistakes
  8. Frequently asked questions
  9. Checklist

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: scriptTagCreate and scriptTagUpdate return 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.
where the app's code livesbefore: the app edits the themelayout/theme.liquid+ a pasted <script>snippets/app-badge.liquidwritten by the Asset APIsections/main-product.liquid+ {% render 'app-badge' %}script tagremote JS on every pageon uninstall: the code stayswith a theme app extensiontheme: unchangedstays on its upgrade pathblocks/stock-badge.liquidapp block, added by the merchantblocks/help-bubble.liquidapp embed, turned on in the editorassets/help-bubble.jsserved from Shopify's CDNon uninstall: Shopify removes the blocksscript tags: no new ones since Oct 1, 2026they stop loading on storefronts on March 1, 2027 · source: shopify.dev

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 blockApp embed
targetcontent (section is the legacy value and still works)head, compliance_head or body
Where it rendersInside a section, wherever the merchant puts itBefore </head> or </body>
ThemesOnline Store 2.0 only: JSON templates and sections that accept @app blocksVintage and Online Store 2.0
DataCan point at dynamic sources with autofillOnly the page's global Liquid scope
After installNot in the theme until the merchant adds itDeactivated until the merchant turns it on
Good forReviews, star ratings, notices on the product pageChat 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.

two kinds of block in one extensionapp blockapp embedtargetcontenthead · compliance_head · bodywhereinside a sectionbefore </head> or </body>themesOnline Store 2.0 onlyvintage and Online Store 2.0datadynamic sources (autofill)global Liquid scope onlyafter installthe merchant adds itoff until turned onforreviews, product noticeschats, badges, pixelsneither one renders on checkout pagesthe schema target decides the typesource: shopify.dev, configure theme app extensions

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
  1. --template theme_app_extension picks the type; leave it out and the CLI asks. --name names the folder and the extension.
  2. assets/ holds CSS, JavaScript and images, which Shopify serves from its CDN.
  3. blocks/ holds one Liquid file per app block or app embed. The file name is the block's handle.
  4. snippets/ holds Liquid shared between blocks; locales/ holds translations for the storefront and for the editor.
  5. shopify.extension.toml only needs name and type = "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 %}
  1. The liquid tag reads the product from the product setting. Because that setting has autofill, Shopify fills it with the product of the section the block is added to.
  2. selected_or_first_available_variant is the variant selected in the URL, or the first available one.
  3. The condition checks inventory_management == 'shopify' because, per the Liquid reference, when inventory is not tracked inventory_quantity returns the number sold, and the notice would be wrong.
  4. The text comes from locales/ through the t filter, so the store shows it in its own language. The color goes in as a CSS variable.
  5. "target": "content" makes it an app block; enabled_on limits it to the product template.
  6. stylesheet loads assets/stock-badge.css only on pages where the block is present.
  7. The t: labels come from en.default.schema.json and es.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 %}
  1. "target": "body" makes it an app embed: Shopify injects its HTML before </body>.
  2. javascript loads assets/help-bubble.js only when the embed is active on that page. If several blocks reference the same file, it is included once.
  3. enabled_on limits 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.
  4. 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:

LimitValueType
All files in the extension10 MBEnforced
Blocks30Enforced
Locale files / size of each100 / 15 KBEnforced
Liquid across all files100 KBEnforced
Compressed CSS referenced in the schema100 KBSuggested
Compressed JS referenced in the schema10 KBSuggested

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.

the merchant turns the blocks on in the editortemplate: productProduct informationTitlePriceStock badgeapp+ Add block › Appsapp embedsHelp bubblepreviewOnly 3 left in stockHelp ×the merchant decides where and whenillustrative: the two blocks from this article, theme untouched

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:

  1. Ship the extension with an app embed that does what the script tag did.
  2. 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, where api_key is the client_id in your shopify.app.toml and help-bubble is the block's file name.
  3. Confirm it is active: app.extensions() from your app in the admin returns active or available per block; from your backend, read the published theme's config/settings_data.json with the read_themes scope.
  4. 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 }
  }
}
  1. scriptTags returns only your app's script tags, up to 50 per page.
  2. src tells you which file each one loads and displayScope where it runs; if it is order_status or all, that part has already stopped working.
  3. scriptTagDelete takes the id and needs the write_script_tags scope.
  4. userErrors comes 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: use content.
  • 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_quantity without 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 autofill and enabled_on.
  • JavaScript lives in assets/ and loads through javascript only on the templates that need it.
  • Text comes from locales/, for the storefront and the editor.
  • shopify theme check passes 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

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 19, 2026 · updated November 20, 2026

← Blog