Managing Shopify App Extensions Across Environments

Recently, Shopify started requiring that any apps integrating with a Theme use Theme App Extensions. There is plenty of documentation related to getting started with Theme App Extensions, such as Shopify’s documentation, but there is very little information available regarding managing these extensions across dev, staging, and production environments. The challenge of managing extensions across environments stems from the way in which Shopify apps are developed, and the restrictions around Theme App Extensions.

When building a single web application on Shopify, it is common for each developer on the team to have their own Shopify application instance within Shopify so that they can view web application code changes they make without impacting the other team members’ development experience. Additional Shopify application instances will exist for other environments, such as staging and production. However, Shopify requires that there can only be one Theme App Extension per Shopify application. When the Shopify CLI command shopify extension create is run in the terminal (and Theme App Extension is selected), a theme-app-extension directory is created in the current directory of the web application (it should be the root of the project). This directory includes a .env file that identifies the selected Shopify application (such as one of the developer apps or the staging/production app). Running the command again causes the Shopify CLI to return an error since only one Theme App Extension is permitted per application*.

A potentially simple update would be to update the .env file in the theme-app-extension directory to point to another Shopify application. However, the environment variables required to target another Shopify application are only available to a Shopify application that has been “registered” with the Theme App Extension. But we can’t create or register a new Shopify application with our current Theme App Extension, so what do we do?!?

After lots of head-scratching, internet searching, and mile-long staring, we found a solution.

1. Rename the existing theme-app-extension directory to anything else, such as theme-app-extension-tmp.

mv theme-app-extension theme-app-extension-tmp

2. Run the shopify extension create CLI command again, targeting a new Shopify application to register.

shopify extension create

3. Remove the auto-generated theme-app-extension directory.

rm -rf theme-app-extension

4. If more Shopify applications need to be registered, start back at step 2. Otherwise, move to step 5.

5. Rename the theme-app-extension-tmp directory back to theme-app-extension.

 mv theme-app-extension-tmp theme-app-extension

In the end, we have our original theme-app-extension directory and have registered all the Shopify applications that we care to register. Now when we navigate in the terminal to the theme-app-extension directory, we can run the shopify extension connect CLI command and are presented with all the registered Shopify applications.

cd theme-app-extension
shopify extension connect

Selecting one will allow us to perform any additional CLI commands targeting that Shopify application’s Theme App Extension.

Hope this saves you the many hours it took us!

*I should note that this post references “application” a lot. There is a difference between “Shopify application” and “web application”. “Web application” is the application code that powers the Shopify application. “Shopify application” refers to the actual application created within the Shopify Partners UI.

Learn more about how The Gnar builds Shopify apps.