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