Theme app extensions framework

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

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.

For app blocks to function, a theme must contain the following:

• JSON templates.

• Sections that support and render blocks of type @app.

  Refer to Dawn's main product section for an example implementation.

You can verify whether a theme supports app blocks .

The following example creates a span element with a style attribute. The style value (color: {{ block.settings.color }}) searches inside of schema for a settings key, and then searches for a color key, which contains the "default": "#000000" value. This value then populates the style attribute with the default color #000000, which renders the App blocks let you build powerful integrations with online store themes! text in black.

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

The following is an example of a wrapped app block:

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.

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. However, your app can provide merchants with a deep link, post installation, to activate an app embed block automatically.

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.

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.

You can control the visibility of an app block or app embed block based on a custom condition. For example, you might want to limit content based on plan tier, or geographic location.

The condition can be included in the block's schema with the available_if attribute, and the state of the condition is stored in an app-data metafield. The metafield can be accessed through the Liquid app object.

For example, if you had an app metafield with the namespace of conditional and key of block1, then you might use the following schema:

The schema for app blocks and app embed blocks is similar to the theme section schema. It supports the following attributes, some of which are unique to app blocks and app embed blocks:

Review the following recommendations for building theme app extensions:

• Autofill
• Deep linking
• Performance
• Theme editor compatibility
• Detecting app blocks and app embed blocks

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 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.

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:

Post-installation, your app can provide deep links to help merchants add app blocks or activate app embed blocks directly in a theme. If a merchant clicks a deep link, then they're taken to the theme editor to preview the app block or app embed block before saving.

Deep linking simplifies your app's installation 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. Merchants can preview the block before saving and have more control over what they include in their online store.

You can implement a deep link to add an app block to the following locations:

• Any JSON template. For example, the Default product template.
• A header, footer, or aside section group. For example, the Header section group.
• Any main section that supports app blocks. For example, the main-product section.
• A specific section that supports app blocks by targeting its ID. For example, the Newsletter section on the index.json template.

After you add the app block in the theme editor, a coach mark helps the merchant move forward with next steps:

Your app needs to redirect merchants to a URL with populated parameters.

Adding and app block to any JSON template

The following is the deep link structure for adding an app block to any JSON template in a new Apps section:

For example, the deep link to add the customer_review.liquid block to the Default product template might look like the following:

Adding an app block to a section group

The following example shows a deep link structure for adding an app block to the header, footer, or aside section group:

For example, the deep link to add the announcement_bar.liquid block to the Header section group might look like the following:

Adding an app block to the main section

The main section is a section with ID="main".

The following example shows a deep link structure for adding an app block to the main section of a template:

For example, the deep link to add the star_rating.liquid block to the main section of the product.json template might look like the following:

The following example of a theme's product.json template includes a section with an id of main.

Adding an app block to a section using its ID

The following example shows a deep link structure for adding an app block to a section by targeting its ID:

For example, the deep link to add the form.liquid block to the Newsletter section of the index.json template might look like the following:

You can find the parameters for the section you want to target in the template’s JSON file. For example, the parameters of the Newsletter of the index.json template are shown below:

In the following scenarios, an error message is shown to merchants to guide them with next steps. When possible, you should take steps to prevent these errors.

You can implement a deep link to activate an app embed block directly in a theme.

Your app needs to redirect merchants to the following URL, with URL query parameters populated:

You can retrieve the <myshopifyDomain> value from the Shop REST Admin API resource or the Shop GraphQL Admin API object.

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.

You need to ensure that the app works in the theme editor environment. If necessary, you can set your app to detect the theme editor, so that you can adjust your app to work in that environment.

If you want to identify whether a merchant has added app blocks to their theme, or enabled app embed blocks, you can use the Asset REST Admin API resource to look for blocks that match your app type.

When a merchant adds an app block to a theme, a reference to the app block is added to the template JSON file.

You can identify your app block by the block type, which uses the following syntax:

An app block is given a unique ID, and the type value is appended with a unique ID which identifies the app.

The following example contains two app blocks from the same app: one in the main-product section, and one in an apps section.

App embed blocks appear in settings_data.json.

An app embed block is added to settings_data.json only after it's enabled for the first time. If the app embed block is disabled after it's been enabled, then it remains in settings_data.json, and disabled is set to true.

You can identify your app block by the block type, which uses the following syntax:

An app block is given a unique ID, and the type value is appended with a unique ID which identifies the app.

Shopify validates theme app extensions when you deploy your extension. If the app's content exceeds any file and content size limits, then the theme app extension fails validation and doesn't update.

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

The following pages and objects can't be used with theme app extensions.

Theme app extension app blocks and app embed blocks can't be rendered on checkout pages. This includes all pages that are rendered when a customer initiates a checkout, such as Contact information, Shipping method, Payment method, and Order status.

Theme app extensions don't have access to the following Liquid objects or properties:

• The content_for_header object
• The content_for_index object
• The content_for_layout object
• Any properties of the parent section object, other than id. You can use the id property to interact with the section rendering API.

App blocks have access to their parent section liquid object. Only the ID property is accessible, which can be used with the section rendering API.

• Get started building a theme app extension.