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

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

shopify extension create

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

rm -rf theme-app-extension

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

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

Comments

[Peter Hallander]

Worth noting for anyone arriving from search in 2024+: the Shopify CLI has changed significantly since this was written and the workaround described here is no longer needed.

Since Shopify CLI v3 (rolled out late 2022/2023), extension management moved to shopify.app.toml and per-environment config uses shopify app config use <config-name>:

# Create named configs for each environment
shopify app config use shopify.app.development.toml
shopify app config use shopify.app.staging.toml
shopify app config use shopify.app.production.toml

Each .toml file can reference a different client_id (the app's API key), which maps to a different app registered in Partners. You can switch between them without the mv + rm dance described above.

The extension TOML (extensions/[name]/shopify.extension.toml) now also supports [[extensions]] array syntax for registering the same extension codebase to multiple app instances, though the extension handle has to match.

For the deep-links in the article's context (getting merchants to install extensions directly), the format has also updated — the addAppBlockId URL parameter now uses {extension-handle}/{block-type} format and needs to point to the correct published extension version, not just the dev build.

The core problem you described (one extension per app) is still real, but the CLI workflow for managing it has improved a lot.