Getting started with theme app extensions
You can start building theme app extensions with Shopify CLI.
Shopify validates theme app extensions when you deploy your extension and create a version. If the app's content exceeds enforced limits on theme app extensions, then the theme app extension fails validation and doesn't update.
What you'll learn
Anchor link to section titled "What you'll learn"After you've finished this tutorial, you'll have accomplished the following tasks:
- Created a theme app extension
- Previewed a theme app extension
- Deployed the theme app extension
- Tested the theme app extension
- Added onboarding instructions in your app
- Published the theme app extension
Requirements
Anchor link to section titled "Requirements"- You've created a Partner account.
- You've created a development store.
- You've created an app that uses Shopify CLI 3.0 or higher, or you've migrated your existing app so it's compatible with Shopify CLI 3.0 or higher.
- You've populated your store with test products.
- You've installed an Online Store 2.0 theme, such as Dawn, that uses JSON templates and supports app blocks.
- You understand the theme app extensions framework.
Step 1: Create a new extension
Anchor link to section titled "Step 1: Create a new extension"You'll use Shopify CLI to generate a new extension.
Navigate to the directory of the app that you want to add your extension to.
Run the following command to start creating the extension:
Select
Theme app extension
as the type of extension.Provide a name for your extension.
You should now have a new extension directory that includes the basic folder structure for a theme app extension. By default, all of the folders are empty.
Step 2: Populate your theme app extension
Anchor link to section titled "Step 2: Populate your theme app extension"Before you can preview your theme app extension, you need to add code that you can preview. If you're just getting started, then consider creating a simple app block as a starting point. For example, you can create a simple app block in the blocks
folder of your theme app extension:
To learn more about the structure and content of a theme app extension, refer to the theme app extensions framework.
Step 3: Preview your theme app extension
Anchor link to section titled "Step 3: Preview your theme app extension"After your theme app extension is created and you've added some basic code, you can preview your changes in real time by starting a local development server.
The dev
command returns a preview URL that hot reloads local changes, allowing you to preview changes in real time using the store's data. This preview is available only in Google Chrome.
Navigate to your app directory.
Run one of the following commands:
You can specify which theme you want to use to host your theme app extension using the--theme <ID or name>
flag. If you don't specify a theme, then the command will upload Dawn, Shopify's example theme, to the development store.
When you run thedev
command, the CLI builds your app and bundles your app extensions. It also walks you through multiple configuration steps. If you've already rundev
ordeploy
for this app, then some of these steps are skipped.To learn about the processes that are executed when you run
dev
, refer to the Shopify CLI command reference.Follow the instructions in the CLI output to preview the theme app extension. This includes the following steps:
- Enabling development store preview for the extension in the Partner Dashboard.
- Opening the host theme in the theme editor and adding your app block or app embed block to the theme.
Click the URL that's printed at the bottom of the CLI output to preview your extension.
Step 4: Deploy your app to create a draft version
Anchor link to section titled "Step 4: Deploy your app to create a draft version"After your extension is created, you can deploy your extension code to Shopify. The deploy
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.
- Navigate to your app directory.
Run one of the following commands:
When you run the
deploy
command, the CLI builds your app, bundles your app extensions, and deploys the extensions to Shopify as drafts. It also guides you through multiple configuration steps. If you've already rundev
ordeploy
for this app, then some of these steps are skipped.To learn about the processes that are executed when you run
deploy
, refer to the Shopify CLI command reference.After you deploy the extension to Shopify, navigate to your app in the Partner Dashboard, click Extensions, and click the name of the extension.
In the Development Store Preview section, click Enable.
Step 5: Test your changes
Anchor link to section titled "Step 5: Test your changes"Verify that your app looks and behaves correctly by testing your changes on a theme in your development store.
In your development store, go to an Online Store 2.0 theme and navigate to the theme editor.
Follow the procedures for:
Verify the app behaves as expected. For some examples of what to look for, refer to the recommendations for lifecycle management.
Step 6: Include onboarding instructions in your app
Anchor link to section titled "Step 6: 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 7: Publish the theme app extension
Anchor link to section titled "Step 7: Publish the theme app extension"After your theme app extension is ready for online stores, you can deploy the latest code and make the app extension public.
- Navigate to your app directory.
Run one of the following commands:
After you deploy the extension to Shopify, navigate to your app in the Partner Dashboard, click Extensions, and click the name of the extension.
Click Create version to create a version of your theme app extension.
Click Publish beside the version that you want to publish, and click Publish in the popup modal to confirm.
It might take up to five minutes for merchants using the app to be upgraded to the new version. For more information about extension versioning and publishing, refer to Deploy and publish an app extension.