Theme app extensions: apps that do not touch your code

Before extensions, an app that needed to appear on your storefront had two options: write a snippet into your theme files during install, or inject a script tag into every page. Both worked. Both left a mess.

The snippet approach meant the app’s code became your code. It survived the uninstall, because an app cannot reliably reverse an edit to a file you may have changed since. Audit an established Shopify theme today and you will find fragments of apps nobody remembers buying — a div waiting for a reviews widget that was cancelled two years ago, a block of Liquid guarding against an object that no longer exists. Every one of those is a thing a developer has to decide about before they can safely change the page around it.

Script tags were tidier to remove and worse to live with, because the app’s JavaScript loaded on every page whether or not it was needed, and you had no control over where in the page it landed or what it did when it got there.

Shopify’s position on both is now clear. The REST Admin API became a legacy API as of 1 October 2024, and from 1 April 2025 all new public apps must be built exclusively on the GraphQL Admin API. On script tags specifically, the documentation states they work only with vintage themes, and that apps integrating with Shopify themes must use theme app extensions instead. If an app you are evaluating still asks you to paste code into theme.liquid, that tells you when it was last meaningfully worked on.

An extension is a small, self-contained bundle with three kinds of thing in it, per Shopify’s documentation: blocks, which are Liquid files acting as the entry point for whatever the app injects; assets, meaning the CSS, JavaScript and static content that get served alongside them; and snippets, reusable Liquid the blocks share.

It lives with the app, not with the theme. That is the whole design. The app developer versions and deploys the extension on their own release cycle; the merchant’s theme is untouched by the deployment, and a merchant who switches theme does not lose the app — they re-add the blocks in the new theme’s editor.

Two block types cover different jobs. An app block is one a merchant adds inside a theme section and positions like any other block: a review star rating under the product title, a size chart above the buy button, a delivery estimate in the cart. The merchant decides where it goes, and can move or remove it without a developer. An app embed block is activated rather than positioned, and is the right shape for anything that is not tied to a place on the page — the app’s script, a floating element, a chat launcher.

The distinction matters when you are judging an app. An app whose visible output is an app block is one you can place, move and remove yourself. An app that delivers everything through an embed block and then paints wherever it likes is back to being something you have less control over, extension or not.

The JavaScript figure is the interesting one, and it is marked *suggested*, not enforced. Ten kilobytes compressed is a sensible budget for a widget. It is also nowhere near what a full reviews platform, a personalisation engine or a chat product actually ships. Nothing stops an extension exceeding it.

So the headline of this post is true and incomplete. A theme app extension keeps an app out of your theme’s files. It does not keep the app’s JavaScript off your pages, and it does not make that JavaScript cheap. If your store is slow because it carries eleven apps, moving all eleven to extensions changes the maintainability of your theme and very little about your Largest Contentful Paint.

The upside is that extensions make the cost legible. Because each app’s assets are its own, you can see which app is responsible for which bytes — which is a conversation you could not have when everything was concatenated into the theme’s own bundle. Use that. A performance review on an extension-based store is a list with names against the numbers.

A handful of documented constraints catch people mid-implementation, and they are cheaper to know now.

Checkout is out of bounds. App blocks and app embed blocks cannot be rendered on checkout pages, and that covers the whole transaction including payment and the order status page. Checkout has its own extension model; do not plan to reach it from a theme app extension.

Three Liquid objects are unavailable. Extensions cannot access content_for_header, content_for_index or content_for_layout. If your design depended on reading or wrapping the layout, it needs rethinking.

An app block can barely see its parent section. Only the parent section’s ID property is accessible, which is deliberate — that ID is what the Section Rendering API needs to re-render the section later. An app block that wants to know what colour scheme or padding the surrounding section chose cannot ask; it has to expose its own settings and let the merchant match them.

The JSON is stricter than a theme’s. Extension JSON cannot contain comments or trailing commas, both of which standard theme files tolerate. It is a five-minute bug the first time and never again.

If you are building a custom app for your own store, an extension is almost always the right delivery mechanism for anything that appears on the storefront. It keeps your app’s front end out of your theme, which means the theme can be rebuilt without also rebuilding the app, and it gives your merchandising team a block they can place without asking you. On the stores we maintain, that second property is the one that pays back.

But be honest about whether you need an app at all. A theme app extension requires an app — with a Partner account, a deployment pipeline, a hosted back end if it does anything server-side, and an OAuth relationship somebody has to keep alive. That is a lot of apparatus for something a theme section would do. If the thing you want is a configurable banner, a tabbed content block or a size chart, build a theme section: no app, no deployment, no dependency.

The dividing line we use is whether the feature needs to hold state or talk to something outside Shopify. A block that renders data your theme already has is a section. A block that needs a database, a third-party API, a background job or logic you do not want sitting in public Liquid is an app with an extension in front of it. Everything in between is usually a section, and the instinct to reach for an app is usually the expensive answer.

• Custom Shopify apps and back ends
• Theme architecture: settings, blocks and the limits of each
• Shopify maintenance and theme health