Skip to main content
Published in Engineering Insights

Managing Shopify App Extensions Across Environments

Managing Shopify App Extensions Across Environments
Table of contents
  1. Which Shopify CLI version are these steps for?
  2. How do you set up dev, staging and production apps with Shopify CLI today?
  3. What is shared across environments, and what changes per app?
  4. How do you test a theme app extension on a dev store?
  5. How do you release an extension to staging before production?
  6. How do you deploy each environment from CI?

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

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

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

Shell
shopify extension create

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

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

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

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

Which Shopify CLI version are these steps for?#

The steps above and two FAQ answers below use Shopify CLI 2 commands. Those answers name shopify extension create and shopify extension connect. Shopify's CLI 2 repository is now archived. Its README says CLI 2 is deprecated, with a sunset date of May 31, 2023. The current Shopify CLI is version 5.0.1, released November 4, 2026. It has no extension commands. Extension work now sits under the shopify app commands.

This post opened its CLI 2 workaround with one line: "After lots of head-scratching, internet searching, and mile-long staring, we found a solution." Shopify CLI now lets you link several Shopify apps to one codebase. Shopify says you can give each of development, staging and production its own app.

The table maps each task in this post to its command in Shopify CLI 5.0.1.

TaskShopify CLI 2 (this post)Shopify CLI 5.0.1
Create the extensionshopify extension createshopify app generate extension
Add another appRename the folder, create, then restore itshopify app config link
Pick the app a command targetsshopify extension connectshopify app config use, or the --config flag on one command
Release changes to storesNot covered in this postshopify app deploy

Shopify's app extensions guide says you create extensions with the app generate extension command. By default, the CLI looks for extensions in an extensions/ folder. Each extension keeps its settings in its own shopify.extension.toml file.

How do you set up dev, staging and production apps with Shopify CLI today?#

Keep one project and give each environment its own Shopify app. The shopify app config link command links an app and writes a config file for it. If a shopify.app.toml file already exists, it asks for a name and writes shopify.app.{your-config-name}.toml. The shopify app config use command sets the default app. The --config flag picks the app for one command.

This post began from a common setup: "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." With the current CLI, each of those app instances becomes one linked config file. Shopify's import guide says apps for different environments can share a single local project.

  1. Create one app per environment. In the Dev Dashboard, go to Apps and click Create app. This post's footnote and one FAQ answer below name the Shopify Partners UI instead. Shopify's Dev Dashboard migration page says apps built in the Partner Dashboard now sit in that same Apps list. The config link command can also create a new app for you.
  2. Link a development or staging app first. Shopify says shopify.app.toml acts as the default target for commands. You can add the production app later.
  3. Run shopify app config link again for each other app, and give each config file a name when asked.
  4. Set your everyday default with shopify app config use.
  5. Override the default for a single command with --config.
  6. Decide which config files to commit. Shopify says you don't need to commit every one. You might gitignore some development configs, or commit only production.
Shell
shopify app config link
shopify app config use development
shopify app dev --config staging

These lines assume config files named shopify.app.development.toml and shopify.app.staging.toml. The link command asks for a name like these when a shopify.app.toml file already exists. So these two are apps you linked after that file was made. Shopify's guide to app config files uses those names in its own examples. Before any deploy, it says to pass the correct config or run shopify app config use first. The deploy command then shows a summary of config changes for you to confirm.

What is shared across environments, and what changes per app?#

The extension code and its uid are shared across environments, while each app's identity is not. Shopify's deployment guide says extension UIDs "can be shared across production, staging, and development apps." Each app keeps its own client ID and its own Dev Dashboard settings. So one copy of each extension can serve every app.

This post described the CLI 2 setup it had to work around: "This directory includes a .env file that identifies the selected Shopify application (such as one of the developer apps or the staging/production app)." With the current CLI, the uid in shopify.extension.toml identifies the extension instead. Shopify adds it when you run shopify app generate extension or shopify app deploy.

ItemShared or per appWhere it lives
Extension codeSharedThe extensions folder
Extension uidSharedshopify.extension.toml
Client IDPer appclient_id in each app's config file
Secrets, icon, contact email, IP allowlistPer appThe Dev Dashboard, not the config file
App block deep linksPer appBuilt from the app's api_key, which equals its client_id
App metafield namespaces in LiquidSame code in every appThe $app reserved prefix

Shopify's theme app extension docs say the reserved prefixes remove the need to hardcode app IDs. Shopify gives testing and production as examples of the environments this helps.

Some projects still carry extension IDs that shopify app deploy used to write to a .env file. Shopify's extension migration guide covers the switch. A one-time interactive deploy creates the uid values and maps them. Until then, non-interactive deploys with --allow-updates and shopify app dev both fail. After the mapping, the .env extension IDs are no longer used.

Commit the new uid values. For each other app, merge them into that app's code branch and run shopify app deploy --config <name>. Shopify warns that removing and adding an extension can cause data loss on installed stores. If the deploy prompt lists an extension as new and removed, instead of updated, it failed to map.

How do you test a theme app extension on a dev store?#

Run shopify app dev with your development app's config, then add the app block in the theme editor. Shopify's theme app extension tutorial says the dev command starts a local server with hot reloading. The preview works only in Google Chrome. Your dev store needs an Online Store 2.0 theme that supports app blocks.

This post's CLI 2 steps ended with a choice of app: "Selecting one will allow us to perform any additional CLI commands targeting that Shopify application's Theme App Extension." The --config flag now makes that choice for one command, as in shopify app dev --config development.

  1. Pick the host theme with --theme and a theme ID or name. Without it, the CLI uploads Dawn, Shopify's example theme, to the dev store.
  2. Follow the CLI output to open the host theme in the theme editor.
  3. Add your app block to the theme, then save the theme.
  4. Open the preview URL printed at the bottom of the CLI output.
  5. In the theme editor, check that you can add, remove and reposition the app block and change its settings.

How do you release an extension to staging before production?#

Deploy to the staging app first, then create the production version with --no-release. Release it once staging checks pass. Each deploy creates an app version and, by default, releases it to users. Shopify calls an app version "a snapshot of your app configuration and all extensions." Releasing an older version rolls back.

  1. Run shopify app deploy --config staging.
  2. Test the change on a store that has the staging app installed.
  3. Run shopify app deploy --config production --no-release.
  4. Run shopify app versions list --config production to find the version name.
  5. Run shopify app release --version=VERSION --config production, with VERSION replaced by that name.

Two notes from Shopify's app versions guide matter here. Releasing an app version doesn't release your web app, which you deploy to your own hosting. Some app versions need Shopify's review before release. Shopify's list of app extensions shows theme app extensions as not needing review and approval.

The deploy command also ships everything in the project at once. You can't deploy only some extensions, or your app configuration on its own.

A staging pass covers the store and browser setups you test. A Gnar engineering post on Shopify session tokens describes errors that no developer had seen locally or in QA. It says: "We attempted to replicate this using different combinations of stores and app environments to no avail." The errors appeared when the team mirrored the browser setup Shopify uses for its testing.

How do you deploy each environment from CI?#

A CI job runs the same deploy command with a named config and a service account token. Shopify's CI/CD guide runs shopify app deploy with --config production and --allow-updates. The Shopify CLI 5.0.0 release notes say SHOPIFY_SERVICE_ACCOUNT_TOKEN can automate app releases. The same notes deprecate SHOPIFY_CLI_PARTNERS_TOKEN.

This post's CLI 2 flow ended at a prompt: "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." A CI job has no one to pick from that list. Shopify's config guide says the --config flag suits scripts and CI/CD, so the job names its app that way.

  • A production config file, made with shopify app config link.
  • A service account with the App development permission. Store its token as a secret, exposed as SHOPIFY_SERVICE_ACCOUNT_TOKEN.
  • A step that sets up Node.js and installs your project's Node dependencies, plus a step that installs Shopify CLI.
  • A deploy step with --config and --allow-updates. In non-interactive runs, app deploy needs --allow-updates, --allow-deletes or --no-release.
  • --allow-deletes kept for manual runs only. Shopify warns that deleting configuration and extensions also deletes related data on stores that have the app installed.
  • Optionally, --source-control-url to link the commit to the app version in the Dev Dashboard.
Shell
shopify app deploy --config production --allow-updates

Deploy from a full checkout of the repository. Shopify warns that any extensions missing from the environment you deploy from are removed.

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.

Frequently asked questions

Why is changing the .env file not enough?

The variables needed to target another Shopify application are only available after that application has been registered with the Theme App Extension.

How do I register another application while keeping the original extension?

Rename theme-app-extension to theme-app-extension-tmp. Run shopify extension create for the new application and remove the generated theme-app-extension directory. Repeat for any other applications, then restore the original directory name.

How do I switch the target application afterward?

From the theme-app-extension directory, run shopify extension connect and select a registered application. Further commands then target that application's extension.

What is the difference between a web application and a Shopify application?

The web application is the code that powers the Shopify application. The Shopify application is the application created in the Shopify Partners UI.

What is a Shopify app extension?

An app extension is not an app. Shopify describes it as a way for an app to add its functionality to defined parts of Shopify user interfaces. You create one with shopify app generate extension, and its settings live in a shopify.extension.toml file inside the app's extensions folder.

How do I test a theme app extension before release?

Run shopify app dev. It starts a local server with hot reloading, and the preview works only in Google Chrome. Pass --theme with a theme ID or name to pick the host theme. Otherwise Shopify CLI uploads Dawn to the dev store. Then add your app block in the theme editor.

Can one theme app extension serve dev, staging and production apps?

Yes, one copy of the extension can serve all three apps. Shopify's docs say extension UIDs can be shared across production, staging and development apps. Deploy the same code to each app by passing that app's config name with --config.

What is an extension-only app?

An extension-only app is made up entirely of extensions. Shopify can host it, so you need no backend of your own. Shopify's docs also say extension-only apps can only be installed with custom distribution.

Stay In The Loop

Never miss an update. Get the latest blogs, webinars, and expert insights straight to your inbox from The Gnar.