Migrate your app to theme app extensions
This guide explains how to migrate apps to theme app extensions.
Theme app extension benefits
Apps that integrate with online stores will traditionally modify theme code to inject assets, extract data, and extend theme functionality. Merchants are frequently required to edit theme code, which can be intimidating and error-prone. Uninstalling apps often leaves the code edits, or ghost code, behind in the theme, which can cause quality and performance issues and takes merchants off their theme upgrade paths.
For example, apps often require the following to integrate with online stores:
Adding snippets to the
snippetsdirectory of a published theme, which are then added to a page by modifying Liquid layout, template, or section files.
Theme app extensions don't edit theme code, which provides the following benefits:
Reduced risk of an app introducing breaking changes to the theme
Minimized app support debt
Increased app adoption by offering merchants a cleaner experience for app integration and customization.
Increased user retention owing to a graceful, out of the box integration experience.
Theme app extensions reduce the effort required to integrate apps in themes. You aren't required to build integration logic and installation instructions for the different themes on which the app might be installed. Instead, you can build once for all of the themes where your app is installed. Updating your app also won't require you to build theme-specific support.
Theme app extensions automatically expose your app in the theme editor, so that you can leverage the editor’s visual editing capabilities without needing to replicate them in your app.
When to migrate to app blocks
Migrate to app blocks if your current method of theme integration includes the following types of actions:
AssetREST Admin API resource to add content to a published theme's snippets directory and rendering the content by modifying Liquid layout, template, or section files.
For more use cases and information about app blocks, refer to the theme app extensions framework.
When to migrate to app embed blocks
Migrate to app embed blocks if your current method of theme integration includes the following types of actions:
Assetresource to add scripts to the theme and
<script>tags to the theme.
Assetresource to add Liquid to the head of the document in
For more use cases and information about app embed blocks, refer to the theme app extensions framework.
Not migrating your app
Merchants will increasingly adopt Online Store 2.0 themes, including Dawn, Shopify's Online Store 2.0 reference theme.
Apps without theme app extensions might not integrate as well with Online Store 2.0 themes. If your app continues to edit theme code, then merchants might not be able to upgrade their themes. Both scenarios represent a poor merchant experience and could negatively impact your ability to attract new app users and retain existing users.
Migrate your apps
If you'll use app blocks, verify whether online stores that use your app have published themes that support app blocks.
If a published theme supports app blocks, then your app should skip all POST requests made to the
Complete the Getting started with theme app extensions tutorial to learn how to build a theme app extension.