To ensure that building Shopify apps provides the best experience for both merchants and developers, we're continuously working on new processes to improve app development. With our new theme app extensions, building apps for merchant's storefronts has never been easier.

When building a Shopify app that interacts with the online store, one of the most difficult aspects that developers encounter is ensuring that their app integrates safely and easily with all themes, while still being straightforward for a merchant to install.

Shopify's theme app extensions aim to remove this challenge by introducing a new streamlined method for apps to interact with themes, that improves the experience for both developers and merchants. Theme app extensions also ensure that apps integrate seamlessly with OS 2.0 themes, which we expect more merchants will continue to adopt throughout this year.

Merchants shouldn't concern themselves with code. Generally, they aren't technical and, even if they are, they need to spend their time on their business. We actually opted to delay our launch and migrated over to the new theme app extension framework.

Ryan Macdonald, CTO, Obsidian Apps

App developers are already adopting theme app extensions and seeing the benefits. "Merchants shouldn't concern themselves with code. Generally, they aren't technical and, even if they are, they need to spend their time on their business," Ryan Macdonald from Obsidian Apps says. "We actually opted to delay our launch and migrated over to the new theme app extension framework."

In this article, we'll unpack how apps work with Shopify themes, the advantages of using theme app extensions, and how to get started with this approach for your own app. We'll also learn how some Shopify app developers have implemented theme app extensions and what their experiences have been.

How apps integrate with Shopify themes

At Shopify Unite 2021, we released Theme App Extensions as part of Online Store 2.0 with a major update to how apps integrate with the storefront. Here’s a high level look at how both the old and new approaches work.

Without theme app extensions

infographic os a workflow without theme app extensions

Without theme app extensions, apps use the Asset API which gives them full read/write access to theme files. They then proceed to add and modify any number of files to get their app integrated into the theme. There are a number of issues with this approach:

Developers need to determine exactly where to insert their code into the theme, which can vary depending on the theme.
Apps may inadvertently break themes or introduce performance degradation issues.
When an app is uninstalled, the code that was added isn’t removed, which leads to code running that is no longer needed or may no longer work.
Shopify’s theme update mechanism only works on themes without code edits, so this approach prevents merchants from receiving updates to their theme, potentially blocking them from the latest features for their online store.

With theme app extensions

image of the structure with theme app extensions

With theme app extensions, all the issues outlined above are solved as app developers no longer need to modify theme files directly. Instead, Shopify provides a way to build blocks that are added to a theme by the merchant in the editor and injected at render time by the platform.

This avoids any potential integration bugs, keeps the theme untouched and eligible for updates and the app is automatically removed from the theme when uninstalled, no further cleanup needed. Furthermore, all of your theme app extension assets (liquid, CSS, JS, SVGs) are hosted on the Shopify platform and delivered through our CDN for fast performance all over the world.

What are blocks?

To understand theme app extensions, you first need to understand what blocks are in themes and how merchants interact with them.

Blocks are modules of content that can be added, removed, and reordered within a section. This allows merchants to have granular control over the look and feel of every aspect of their online store.

To learn more about blocks in themes and how they are structured, take a look at our blog article How to Work With Shopify Theme Blocks.

Benefits of using theme app extensions

This improved workflow that brings apps and themes closer together has a range of benefits for both developers and merchants. With a streamlined approach for interacting with a merchant's store, theme app extensions simplify the process for adopting, managing and uninstalling apps.

Here are some examples of how adopting theme app extensions impacts positively on the merchant and developer experiences:

1. Apps now integrate seamlessly without modifying theme files

Arguably the biggest advantage of an app that uses theme app extensions is that merchants won’t need to manually edit their theme code to install your app. This means that merchants will be able to get up and running quicker with your app, and the general experience of using your app will be improved, leading to a higher satisfaction rate.

With this safer install process, app developers can expect less support debt as merchants will run into less issues when installing your app. In general, an app which doesn't inject code greatly reduces the risk of an app introducing any breaking changes to a merchant's store. The positive impact of this will be especially felt during busier times of the year as you'll be able to assist more merchants who contact your support teams.

Additionally, since your app will not be modifying theme files, merchants will also be able to upgrade their theme more easily, and continue using your app even when they update to a new version or switch themes.

2. No longer a need to build theme specific solutions

App developers no longer need to build custom integration logic or publish specific instructions to allow merchants to install their app onto every existing theme. With the recent reopening of the Shopify Theme Store for new submissions, the ability for apps to integrate in a theme-agnostic method is great news for app developers.

App blocks will automatically work for all Online Store 2.0 compatible themes, while app embed blocks are supported in both vintage and in Online Store 2.0 themes, because they don't rely on sections or JSON templates. With this model, there is no requirement for theme app extensions to be compatible with a specific theme structure in order to be installed.

Time consuming tasks such as publishing and updating install instructions, or creating logic within an app that would be able to identify and respond to a specific theme, is no longer required by developers who adopt theme app extensions. With this time saved, you can reinvest efforts into enhancing your app, or building a new product for merchants.

3. No need to implement a code removal process

Previously when a merchant uninstalled an app, the app's code snippet would remain on a theme, resulting in bloated code, potential performance issues, and could lead to merchants being dissatisfied with apps. To counter this, app developers would often need to implement a manual task that would remove old redundant code, which is unreliable since theme code is not standardized.

By using theme app extensions, uninstalls are now much cleaner as there is no redundant code remaining on a merchant's theme. This means there's no longer a need for app developers to manually implement a process to remove code following an uninstall, and merchants will have a more positive experience with your app.

4. Apps can now leverage Shopify's CDN for assets

With theme app extensions, your app can contain Javascript and CSS files within a /assets subdirectory which is then automatically rendered by Shopify's own CDN for fast reliable delivery all over the world. This boost to performance will mean that your app components will load quickly for merchants, as well as simplifying how your assets are loaded.

For app embed blocks, you can go even further with performance and take advantage of their ability to only load scripts on specific pages.

5. Easily manage versions and deploy to all of your merchants

The workflow for publishing new versions of your app to merchants is also improved with theme app extensions. The Shopify CLI can be used to upload a draft version of your app by running shopify extension push which allows you to verify that all functionality is working correctly.

After a successful push, and once you're satisfied with the new changes, the CLI will generate a link to your Partner Dashboard where you can create a new version and publish your extension. This action will automatically deploy your theme app extension to all the online stores that use it.

6. Simplified onboarding flow with deep linking

If your app uses app embed blocks, following installation, you can prompt merchants with deep links. When clicked, these deep links activate app embed blocks in the theme editor for merchants to preview and adjust before saving and publishing.

Deep linking simplifies your app's installation flow, because merchants won't need to navigate to the theme editor, find the block, and then act on it. Instead, your app does the work for them. Because merchants can preview the block, you're providing them with control over what they include in their storefront.

These benefits demonstrate how both merchants and developers can experience an improved workflow with theme app extensions. This will increase the satisfaction merchants have with your app, as well as allow you to focus on building new apps by avoiding time-consuming processes.

7. A better overall UX experience for merchants

The standardized process for working with apps, that theme app extensions introduce, allow merchants to become more familiar with how to integrate apps into their store. With this new approach, merchants will have a consistent experience when installing and using apps, which will empower merchants to get the most out of your apps.

In addition, merchants can now adjust app settings right in the theme editor and visualize those changes as they are edited. By cutting out complexity, the overall experience of working with apps will be easier for merchants, and app developers can benefit from less support requests, and a higher adoption rate.

Structure of a theme app extension

A theme app extension is a bundle of files that follows a structure very similar to themes. Below is an overview of the file structure to follow when building a theme app extension.

assets: Contains CSS, JavaScript, and other static app content that can be referenced within the theme app extension and injected into the theme. These assets will be served via our CDN.
blocks: Contains app block and app embed block Liquid files. When an app is installed on a shop, the app block and app embed blocks are automatically made available to merchants via the theme editor.
snippets: Contains Liquid snippet files, which are bits of code you can reference in other app blocks and app embed blocks.

Types of app blocks

Apps can extend themes using two types of blocks: app blocks and app embed blocks.

image of a mock web page with sketch sneakers and ratings — App block added to a section

image of a mock web page with the template added and ratings — App block added to a template as a section

image of a mock webpage with a chat bubble — App embed block added to a theme

App block

App blocks are used to inject content or functionality within a theme section or as a full-width section on a page (i.e. product reviews, back in stock notification, instagram feeds, etc.) App blocks can be added, removed, reordered and configured by merchants in the theme editor. They provide the ultimate flexibility when it comes to placing your app exactly where the merchant wants it.

Okendo is a popular Shopify app that showcases customer-generated content like product ratings and reviews, photos and videos, and Q&A. Theme app extensions provided more flexibility to place code where needed without having to leverage the Shopify API, simplifying the install process and maintenance.

I liked how Shopify allowed us to include our own JS and CSS assets into the app block. Before apps had to load in external scripts and stylesheets to work, now it can be declared within the scope of the app only, and doesn't have to be referenced in a theme file. It lightens the load on our team, and merchants, when installing/uninstalling apps.

Minh Vũ, Software Engineer, Okendo

Another good example of keeping merchant UX at the forefront is how email marketing app Seguno was able to leverage theme app extensions so merchants can seamlessly integrate newsletter sign-ups on chosen pages on their storefront. Building a smooth install experience for merchants was top of mind for Seguno, as they were able to do it directly in the theme editor.

app-extensions-demo

We found merchants easily discovered this capability since it's right inside the theme editor and have seen a reduction in support requests about integrating storefronts with Seguno.

Marc Baumbach, Co-founder and Head of Engineering, Seguno

App embed block

App embed blocks are used to add functionality that is detached from the theme’s layout (i.e. modals, chat bubbles) or that has no visual components (i.e. analytics, SEO optimization).

Incentivize is a mobile-first cart with upsells and incentives, helping merchants upsell the right products at the right time to increase conversion. With the Shopify CLI integration, they were able to move app code from self-hosted files into the theme app extension framework, which reduced the complexity and size of their codebase.

Additionally, prior to theme app extensions, deploying new code frequently would require many different app versions and conditionally serve different script tags. Theme app extensions provide a framework to respond faster to bugs and revert back to previously published versions.

"Theme app extensions provide us with a framework to respond quickly to bugs and revert to a stable version stress-free. I couldn’t live without theme app extension versioning now."
Ryan Macdonald, CTO, Obsidian Apps

Below is an example of Incentivize being added as an app embed in a theme.

app-embed-demo

Deconstructing app blocks

Let’s look at the content of an app block. The example below is for an app block but an app embed block would follow the same pattern.

First, everything that’s above the {% schema %} tag is the body of the app block. This is where you define what your block will render once added to a section. The body is built using HTML markup and Liquid. Aside from a few restrictions, developers can expect the same Liquid objects, tags and filters that are available in themes.

Next is the app block’s schema, a JSON structure that defines the block’s attributes:

name: the name of the block as shown to merchants in the theme editor
target: where the block will be located. Use “section” for app blocks and “head” or “body” for app embed blocks
javascript / stylesheet: a javascript / stylesheet file to load from the assets folder. These assets will only be loaded if the block is present on the page. It will also only be loaded once regardless of how many times the block is present on the page.
templates: the templates on which a block can be added. The theme editor will show the app block in the picker only for the templates specified here. If not set, then Shopify defaults to all supported templates.
settings: settings that will be shown to merchants in the theme editor. These settings can be referenced in your block’s body and used to configure it’s look and behavior. App blocks support all the same setting types that are available in themes.

See our docs on app block schema for a full list of attributes that can be set in an app block’s schema.

Adding app blocks to a theme

When a merchant adds an app block to a template or a section of a theme from the editor, it’s settings are stored in that page’s JSON template. If a merchant adds the same app block multiple times to a theme, each instance will have their own set of settings stored in the appropriate JSON template.

Since app embed blocks are global to a theme, they can only be enabled/disabled via the theme editor’s Theme settings area. When a merchant enables an app embed block, it’s settings are stored in the theme’s settings_data.json file.

Gid showing the app extensions theme setting in checkout

Theme compatibility

App embed blocks are supported on all themes, however, app blocks will only be accessible to themes that have been updated to use JSON templates in the /templates directory. Additionally, app blocks require that the target section supports blocks of type @app.

To see an example of how this could be implemented on a theme's product page, you can see the main product section of the Dawn theme, which contains a block with a type of @app within it's schema settings. You can follow the steps in our developer documentation to determine and verify if a theme will support your app’s app block.

Verify your code using theme check

When you're building a new app, or migrating your existing app to use theme app extensions, you can use Shopify's Theme Check tool to help keep you on the right track.

The theme check linter is a powerful tool to help detect errors in your theme app extension’s liquid code and ensure that you're following best practices. Theme check can be run from the Shopify CLI by using shopify extension check from within your theme-app-extension folder. Append -a to auto-correct offenses.

theme-check

Extending into the future

Theme app extensions allow apps and themes to integrate together in a reliable and safe process, which improves the experience for both developers and merchants. With this new approach you can build solutions for Shopify merchants that will be straightforward to work with, and will set your app up for success.

To prepare your app for the future and start building your own theme app extensions for existing or new apps, follow the instructions to get started in our developer documentation.