November 5, 2026 · 8 min read

Theme App Add-Ons: How to Bundle an App With Your Shopify Theme

Shopify's theme app add-ons let theme developers bundle a storefront app directly into a Theme Store listing, so merchants install both in a single flow.

Theme App Add-Ons: How to Bundle an App With Your Shopify Theme

Shopify's theme app add-ons feature, launched on October 28, 2026, lets theme developers bundle a storefront app with their Theme Store listing so merchants can install both the theme and the app in a single flow. The app itself is built as a standard theme app extension (TAE), published independently to the App Store, then linked to the theme inside the Partner Dashboard. That linkage is the "add-on" layer: everything underneath it is ordinary TAE mechanics you should already know.

Key takeaways

  • Theme app add-ons are a Shopify Theme Store feature announced October 28, 2026, not a new extension type.
  • The underlying code is a standard theme app extension: app blocks (target section) and app embed blocks (target head or body).
  • One add-on per theme listing; the same app can be reused across multiple theme listings you own.
  • The partner organization that owns the theme must also own the app.
  • Theme developers building add-ons receive priority placement in the app review queue.

What "bundling" actually means

Before October 2026, theme app extensions existed and worked fine, but the connection between a theme listing and an app was entirely informal. A theme README might say "install App X for best results." Merchants had to find the app separately, install it, then enable it inside the theme editor. Drop-off was real.

Theme developers can now build storefront apps using theme app extensions and bundle them with their theme listings on the Theme Store. The result is that an app add-on is a storefront app, built with theme app extensions, that extends a theme with additional features, and merchants can discover it from the theme listing and install both the theme and app at the same time.

That single-install flow is the meaningful change. The extension code itself follows exactly the same rules it always has.

The building blocks: TAE structure

The theme app extension file structure has a blocks subdirectory containing app block files and app embed block Liquid files, and a snippets subdirectory for Liquid snippet files that you can reference in other app blocks and app embed blocks.

Scaffolding a new extension with Shopify CLI:

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

This creates:

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

The shopify.extension.toml file defines the extension's name and type, and optionally its handle.

Minimal shopify.extension.toml:

name = "my-addon"
type = "theme"

App blocks vs. app embed blocks

Theme app extensions provide your app with two integration types that extend themes in the online store: app blocks and app embed blocks.

Use the right one for the right job:

Integration typetarget valueWhere it appearsMerchant control
App blocksectionInside a section, placed by the merchantAdd, move, remove in theme editor
App embed (head)headBefore closing </head>Toggle in Theme Settings > App embeds
App embed (body)bodyBefore closing </body>Toggle in Theme Settings > App embeds

A typical app block Liquid file:

<div class="my-addon" style="background: {{ block.settings.bg_color }}">
  {{ block.settings.heading }}
</div>

{% schema %}
{
  "name": "My Add-on Block",
  "target": "section",
  "stylesheet": "my-addon.css",
  "settings": [
    {
      "type": "color",
      "id": "bg_color",
      "label": "Background colour",
      "default": "#ffffff"
    },
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "Hello from the add-on"
    }
  ]
}
{% endschema %}

By default, app embed blocks are deactivated after an app is installed. Merchants need to activate app embed blocks in the theme editor, from Theme Settings > App embeds. This is a friction point that the new single-install flow partially solves: the merchant still needs to toggle embeds, but at least they have the app installed before they open the editor.

Making your theme sections accept app blocks

To allow merchants to add app blocks to a section or a theme block, you need to include a generic block of type @app in the section or block schema.

// Inside a section's schema
{
  "name": "Product info",
  "blocks": [
    { "type": "@app" }
  ]
}

The @app type tells Shopify's theme editor to show installed app blocks as available options within that section. Without it, app blocks can only be added as standalone sections, not positioned alongside theme content.

If you are building the theme that will ship with the add-on, you control both sides. Add "type": "@app" to every section where the add-on block makes sense. If the block should only appear on specific templates, use enabled_on:

{% schema %}
{
  "name": "Subscription Widget",
  "target": "section",
  "enabled_on": { "templates": ["product"] }
}
{% endschema %}

You can use only one of enabled_on or disabled_on in a schema, not both.

Block limit: how many blocks can one TAE hold?

As of February 3, 2026, you can include up to 30 app blocks in a single theme app extension, an increase from the previous limit of 25. For most add-ons you will ship 2 to 5 blocks, so this limit is not a real constraint. But if you are building a comprehensive add-on with blocks for product pages, collection pages, cart drawers, and footers, it is worth knowing the ceiling.

Linking the app to the theme listing (the actual "add-on" step)

This is where the October 2026 feature lives. The rules, straight from the official changelog:

The app must meet all App Store requirements and be published before it can be added to your theme listing. Your partner organization must own the app to add it to your theme listing. You can associate only one app add-on per theme, but you can use the same app across multiple themes. App add-ons can be listed or unlisted. Your app name, app card subtitle, pricing info, and featured media will be shown to merchants on your theme listing.

The workflow in the Partner Dashboard:

  1. Build and deploy the TAE with shopify app deploy.
  2. Submit the app to the App Store and get it published (or set it to unlisted if you want a theme-only distribution channel).
  3. Open the Partner Dashboard, navigate to your theme listing, and find the add-on section.
  4. Add the app. The theme listing page will now surface the app's pricing card alongside the theme.

Theme developers building add-ons also get priority in the app review queue. That is a meaningful practical benefit given typical review timelines.

App Store submission: the TAE check

If your app integrates with a Shopify theme and you plan to submit it to the Shopify App Store, you must use theme app extensions. This requirement is enforced at submission time. Automated pre-submission checks now include a theme app extensions requirement check, so you will know instantly if something needs fixing before a reviewer picks up your app.

The most common reason the automated check fails even when you have a TAE set up: you built the extension locally but never ran shopify app deploy to push a released version. The check reads the released state, not your local scaffold. Deploy first, then resubmit.

Common submission blocklist items to verify before you submit:

  • shopify.extension.toml has the correct type = "theme" value.
  • At least one block Liquid file exists under blocks/.
  • The extension has been deployed and is included in an app version that has been released.
  • The app itself meets all standard App Store listing requirements (icon 1200x1200px, subtitle without keyword stuffing, demo store URL).

Performance considerations

Bundling an app with your theme does not exempt it from storefront performance rules. A few things worth inlining into your review checklist:

  • CSS: reference a stylesheet in the block schema ("stylesheet": "my-addon.css"). Shopify scopes and loads it with the block, not globally. Do not dump all your CSS into a global app embed unless it truly needs to be sitewide.
  • JavaScript: same principle. Apps using Shopify's theme app blocks load asynchronously and have minimal performance impact, while older apps that edit theme code directly can affect LCP. The TAE model gives you that async loading for free, but only if you do not block rendering inside the block's own Liquid.
  • App embed position: for analytics or utility scripts, prefer "target": "body" over "target": "head" unless you have a genuine reason to run before first paint.
  • Verify that app embed blocks for floating components are positioned properly without obscuring page content, and confirm you can use the theme editor to activate and deactivate app embed blocks and configure their settings.

Comparison: distribution models for theme-bundled functionality

ApproachWho controls updatesMerchant install stepsApp Store requiredAdd-on listing on theme page
Theme app add-on (Oct 2026)App developer (TAE versioning)Single flow from theme listingYes (published or unlisted)Yes, with pricing card
TAE without add-on linkageApp developerFind app separately, install, enable in editorYesNo
Hardcoded theme featureTheme developerNone (ships in theme)NoNo
Legacy script injection (deprecated)App developer (risky)App install + manual code pasteNo (but required for App Store)No

The add-on model sits cleanly in the middle: you get independent versioning of the app logic, Shopify-managed distribution and billing, and the merchant convenience of a single install.

A note on unlisted apps as theme-only add-ons

One underused pattern: publish the app as unlisted. It never appears in App Store search results. The only way a merchant finds it is through your theme listing. This is useful when the app has no value outside your specific theme's design system, or when you want to keep the feature set proprietary to your theme brand. The app still goes through review, still uses Shopify App Pricing, and still appears in the merchant's installed apps list. It just does not get a public search listing.

For a worked example of how extension versioning interacts with store-level deployments, see the case studies section of this site. For a glossary definition of terms like "app embed block" vs "app block," the glossary has concise entries.

What to verify before you launch

  • Deploy the TAE (shopify app deploy) and confirm the released version includes your extension.
  • Open a development store, install the app, open the theme editor, and confirm blocks appear under the Apps panel.
  • Toggle the app embed off and on in Theme Settings > App embeds; confirm no console errors in either state.
  • Run Theme Inspector on the product page with the block active. Check that your block's assets do not appear in the LCP critical path.
  • Submit the app for review. Watch the automated pre-submission checks. If the TAE check fails, verify deploy state first.
  • After the app is published, open the Partner Dashboard, navigate to your theme listing, and link the app as the add-on.
  • Load the Theme Store listing as a merchant would and confirm the app pricing card is visible.

The entire flow, from scaffold to live add-on, is straightforward once you understand that the "bundling" is a Partner Dashboard configuration step layered on top of a standard TAE. Build the extension correctly first, and the add-on linkage is five minutes of dashboard work.

shopifytheme-app-extensionsapp-blocksshopify-clitheme-store

Frequently asked questions

What is a Shopify theme app add-on?

A theme app add-on is a storefront app, built with a theme app extension, that is linked to a Shopify Theme Store listing so merchants can install the theme and app together in a single flow. The feature was introduced on October 28, 2026. The app itself is a standard App Store app and must be published before it can be linked.

Can I associate more than one app with a single theme listing?

No. Shopify allows only one app add-on per theme listing. However, the same app can be reused across multiple theme listings, as long as the partner organization that owns the themes also owns the app.

Do theme app extensions work on all Shopify themes?

App blocks require an Online Store 2.0 theme that uses JSON templates and supports sections everywhere, such as Dawn or Horizon. App embed blocks are more broadly compatible, but Shopify still recommends Online Store 2.0 themes for full editor integration. Vintage themes require the Asset REST API, which is not recommended for new development.

Seven years of Shopify, on one page.

Roles, projects, stack and certifications are on the resume.

Resume Download PDF LinkedIn