Theme app extensions framework

This guide explains the framework for using apps to extend online store themes.

File structure

A theme app extension is a bundle of app blocks, app embed blocks, assets, and snippets.

When you create a theme app extension, Shopify adds the following theme-app-extension directory and subdirectories to your app:

Theme app extension subdirectory descriptions
Subdirectory Description
blocks Contains app block and app embed block Liquid files.
assets

Contains CSS, JavaScript, and other static app content that gets injected into themes.

Apps can load assets using either the javascript and stylesheet schema attributes or from the asset_url and asset_image_url Liquid URL filters.

snippets Contains Liquid snippet files for the theme app extension, which are bits of code you can reference in other app blocks and app embed blocks.

App blocks

Apps that inject inline content on a page extend themes using app blocks. Merchants can add app blocks to a compatible theme section, or as wrapped app blocks that are added at the section level. Create an app block by setting the target in the schema to section.

By default, themes don't include app blocks after an app is installed. Merchants need to add the app blocks to the theme, from the Apps section of the theme editor.

Use app blocks for the following types of apps:

  • Apps that you want to automatically point to dynamic sources, such as product reviews apps and star ratings apps.

  • Apps that merchants might want to reposition on a page.

  • Apps that should span the full width of a page.

Themes require the following to accept app blocks:

You can verify whether a theme supports app blocks.

Example app block code

Examples of app blocks in a theme

The following is an example of an app block added to a section:

An example of an app block added to a section. The section is beside a product image and is for a product star ratings app block.

The following is an example of a wrapped app block:

An example of an app block added as a section and wrapped to span the full width of the page. The section is below product details and is for a customer review comments app block.

Benefits of app blocks

App blocks are flexible. Merchants can use the theme editor to add, remove, and reorder app blocks at the section level for easy customization.

An app block can use autofill resource settings to automatically point to dynamic sources and ensure that content remains in sync with its parent section. For example, an app block on the Products page can point to a dynamic source to show data for different products as they display on the page.

App embed blocks

Apps that don't have a UI component or that add floating or overlaid elements extend themes using app embed blocks. Shopify renders and injects app embed blocks before HTML </head> and </body> closing tags. Create an app embed block by setting the target in the schema to either head or body.

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.

Use app embed blocks for the following types of apps:

  • Apps that provide a floating or overlaid component to a page, such as chat bubble apps and product image badge apps.

  • Apps that add SEO meta tags, analytics, or tracking pixels.

App embed blocks are supported in vintage and in Online Store 2.0 themes, because they don't rely on sections or JSON templates. However, app embed blocks can't point to dynamic sources, because these blocks only have access to the Global Liquid scope for the page on which they're rendered.

Example app embed block code

Example of an app embed block in a theme

An example of an app embed block injected into a theme's closing HTML body tag. The app provides a floating element on the page and is for a chat bubble app embed block

Benefits of app embed blocks

App embed blocks are supported in vintage and Online Store 2.0 themes. This means any merchant can use your app without you needing to maintain two installation paths: one for vintage themes and one for Online Store 2.0 themes.

After installation, merchants can use the theme code editor to configure app embed block settings for a more customized experience.

App embed blocks allow you to only load scripts on specific pages, which isn't possible with the ScriptTag REST Admin API or GraphQL Admin API resource. Loading scripts on specific pages minimizes your app's performance impact by limiting it to only the pages where it's needed.

Schema

The schema for app blocks and app embed blocks is similar to the theme section schema, but also includes the following attributes:

Schema attributes
Attribute Description Required
name The title in the theme editor for the app block or app embed block. Yes
target

Where the block is located. The possible values are section, head, and body.

The value for app blocks is section. The values for app embed blocks are head and body.

Yes
javascript

A JavaScript file to load from the assets subdirectory.

If the block is present on the page, then you can load this file automatically by adding a <script async> tag in the <head> section of the page.

No
stylesheet

A CSS file to load from the assets subdirectory.

If the block is present on the page, then you can load this file automatically by adding a <link rel="stylesheet"> tag in the <head> section of the page.

No
templates

The templates to which an app block is added, or the templates on which an app block is rendered. If not set, then Shopify defaults to all supported templates.

The possible values are product, collection, article, and blog.

No
class

Additional CSS classes to be included in the wrapping tag element, similar to theme section classes.

Theme app extensions will always include the shopify-block class.

No
tag

If set, then a tag wraps the block's output. If not set, then the output is wrapped in a div

No

Recommendations

Review the following recommendations for building theme app extensions:

Autofill

autofill is an app block setting that's automatically set to dynamic sources when merchants add an app block to a section.

App blocks can include settings in the settings schema object, like sections do. You can give settings that reference resources an additional autofill attribute. autofill indicates that Shopify will determine the setting value automatically when merchants add the app block to a section.

autofill setting values will be set to one of the following dynamic sources:

  • A dynamic source pointing to the parent section's resource setting of the same type.

  • A dynamic source pointing to the template's global resource.

Autofill example

A featured product section will have a setting of type product, which allows a merchant to choose which product to display as featured. An app block that has a product setting with autofill set will automatically use the featured product.

In the following example, block.settings.product will use the section's product setting:

Lifecycle management and versioning

Use the Partner Dashboard to manage your theme app extension's lifecycle.

Shopify CLI's extension push command pushes app updates to draft versions on your development store. You can test your theme app extension in a sandbox environment before publishing to online stores. When you're ready, you can deploy your app to online stores that use it at the same time.

For example, verify that:

  • App embed blocks for floating components are positioned properly without obscuring page content.

  • You can use the theme editor to activate and deactivate app embed blocks and configure their settings.

  • You can use theme editor to add, remove, and reposition app blocks and configure their settings.

  • App documentation, such as app onboarding instructions, is clear, accurate, and complete. To learn more about writing effective help documentation, refer to Help documentation in Shopify Polaris.

Performance

All files inside the assets/ folder are automatically served from Shopify's CDN for fast, reliable asset delivery. Reference your assets by using either the javascript and stylesheet schema attributes or using the asset_url and asset_img_url Liquid URL filters.

For app embed blocks, take advantage of their ability to only load scripts on specific pages.

Limits

The following table provides the limits enforced on theme app extensions:

Enforced limits
App content Limit
All files in a theme app extension 10 MB
Number of blocks 10
Size of Liquid across all blocks 100 KB
Size of CSS (compressed) referenced directly by the schema 100 KB
Size of JS (compressed) referenced directly by the schema 10 KB

Next steps