Shopify theme app extensions: app blocks in themes

Theme app extensions are how a Shopify app adds something to a storefront without editing the theme's files. Instead of writing a snippet into your Liquid and hoping nobody deletes it, the app ships blocks that a merchant places through the theme editor. It's a better model for everyone, and it changes what both theme and app developers need to build.

What was wrong with the old way

Apps used to inject code directly into theme files. The consequences were predictable and universal:

• Uninstalling didn't clean up. Leftover snippets and script tags stayed in the theme, often for years. That's the single biggest cause of the mystery slowdowns in the app audit.
• Theme updates broke apps, because the injected code was in a file that got overwritten.
• Merchants couldn't control placement, so an app's widget appeared wherever the app author decided.
• Debugging was archaeology. Whose code is this, and which app do I uninstall to remove it?

The two extension types

App blocks render inside a section, placed by the merchant in the theme editor. Right for anything visible in a specific position — a reviews widget under the product description, a size guide next to the variant picker, a badge row above the buy button.

App embeds are enabled globally rather than placed. Right for things with no position — analytics, chat widgets, a script that needs to run on every page. Because merchants toggle them from theme settings, they're a clean on/off rather than a code edit.

Both are versioned with the app, removed cleanly on uninstall, and sandboxed enough that they can't break the theme.

What theme developers need to do

Two things, and neither is much work.

Accept app blocks in your sections. Add a block of type @app to the schema of any section where an app's UI plausibly belongs — product form area, product description area, cart, and most content sections:

``json "blocks": [ { "type": "text", "name": "Text", "settings": [] }, { "type": "@app" } ] ``

Omit it and merchants simply cannot place app blocks in your theme. They'll then ask the app vendor for help, who will tell them the theme doesn't support app blocks, and you'll get the email.

Leave room for app embeds. Nothing to build — just don't remove {{ content_for_header }} from theme.liquid, which is where they load. The file structure covers why that object is non-negotiable.

Beyond that, be generous about where app blocks are allowed. A theme that accepts them only in one section is a theme merchants outgrow.

What app developers need to do

If you're building an app with a storefront component, ship it as a theme app extension rather than asking merchants to paste a snippet. Practically:

• Keep the block's markup and CSS scoped so it doesn't inherit or leak styles unpredictably across themes.
• Ship sensible schema settings so a merchant can adjust the block without contacting support.
• Load your own assets, and load them lazily where you can. Every app block is weight on a page, and merchants increasingly audit for it.
• Degrade gracefully when the block is placed somewhere unexpected. Merchants will do this.
• Prefer a block to an embed when the thing has a position. Embeds run everywhere, which is a performance cost you're imposing on every page.

This is part of the wider build-versus-buy question: a well-built app block is cheap for a merchant to adopt and cheap to remove, which is exactly what makes buying reasonable.

The performance angle

App blocks are better than injected scripts but they are not free. Every one adds requests and bytes. The advantage is that they're now visible and removable — a merchant can see which blocks are placed and remove them in the editor, rather than trying to work out which of forty script tags belongs to which app.

That visibility is what makes an app audit possible at all. Twice a year, open the theme editor, look at what's placed, and ask of each block whether it's earning its weight.

The old model made apps invisible and permanent. App blocks made them visible and removable. That's a smaller technical change than it sounds and a much larger practical one.