Getting started with theme app extensions

Start building theme app extensions with Shopify CLI. For more information on extension commands, refer to Shopify CLI extension commands.

Shopify validates theme app extensions when you push to a draft extension version and create a version. If the app's content exceeds enforced limits, then the theme app extension will fail validation and won't update. For more information, refer to the enforced limits on theme app extensions.

Requirements

• Create a Shopify Partner account.

• Create a development store.

• Install Shopify CLI.

• Create an app that can be installed on a store, such as one created with Shopify CLI Node.js or Ruby on Rails commands.

• Install an Online Store 2.0 theme, such as Dawn, that uses JSON templates and supports app blocks.

• Understand the theme app extensions framework. To see app block and app embed block examples in a sample app, refer to Shopify's product reviews app.

Outcomes

At the end of this getting started you will know how to:

• Create and register a theme app extension.
• Test and publish a theme app extension.

Step 1: Log in to your Partner account

Step 2: Scaffold and register a theme app extension

Use Shopify CLI to create a theme app extension scaffold and register the extension with your app.

When Shopify CLI creates the theme app extension, it adds a dedicated theme-app-extension directory to your app.

1. Open a terminal window and cd to the root directory of your project:

2. Create the theme app extension and select the app to which you'll register the extension:

3. Navigate to your new theme extension and register it with your app:

Step 3: Push your app to a draft version

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

1. Push the extension to a draft version in the Partner Dashboard:

2. Use the link returned from the shopify extension push command to access your Partner Dashboard, and then navigate to the new theme extension.

3. In the Development Store Preview section, click Enable.

Step 4: Test your changes

Verify that your app looks and behaves correctly by testing your changes on a theme in your development store.

1. In your development store, go to an Online Store 2.0 theme and navigate to the theme editor.

2. Follow the procedures for:

   • Adding app blocks
   • Activating app embed blocks

3. Verify the app behaves as expected. For some examples of what to look for, refer to the recommendations for lifecycle management.

Step 5: Include onboarding instructions in your app

Provide instructions for what merchants need to do to after installing your app. For more information, refer to the UX guidelines.

Step 6: Publish the theme app extension

After your theme app extension is ready for online stores, you can push the latest code and make the app extension public.

1. Push the extension to the Partner Dashboard:

2. Use the link returned from the shopify extension push command to access your Partner Dashboard, and then navigate to the new theme extension.

3. Click Create Version.

4. When the new version displays in the versions list, click Publish.

It might take up to five minutes for merchants using the app to be upgraded to the new version.