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.
mv theme-app-extension theme-app-extension-tmp2. Run the shopify extension create CLI command again, targeting a new Shopify application to register.
shopify extension create3. Remove the auto-generated theme-app-extension directory.
rm -rf theme-app-extension4. 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-extensionIn 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 connectSelecting 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.
| Task | Shopify CLI 2 (this post) | Shopify CLI 5.0.1 |
|---|---|---|
| Create the extension | shopify extension create | shopify app generate extension |
| Add another app | Rename the folder, create, then restore it | shopify app config link |
| Pick the app a command targets | shopify extension connect | shopify app config use, or the --config flag on one command |
| Release changes to stores | Not covered in this post | shopify 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.
- 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.
- Link a development or staging app first. Shopify says
shopify.app.tomlacts as the default target for commands. You can add the production app later. - Run
shopify app config linkagain for each other app, and give each config file a name when asked. - Set your everyday default with
shopify app config use. - Override the default for a single command with
--config. - 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.
shopify app config link
shopify app config use development
shopify app dev --config stagingThese 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.
| Item | Shared or per app | Where it lives |
|---|---|---|
| Extension code | Shared | The extensions folder |
| Extension uid | Shared | shopify.extension.toml |
| Client ID | Per app | client_id in each app's config file |
| Secrets, icon, contact email, IP allowlist | Per app | The Dev Dashboard, not the config file |
| App block deep links | Per app | Built from the app's api_key, which equals its client_id |
| App metafield namespaces in Liquid | Same code in every app | The $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.
- Pick the host theme with
--themeand a theme ID or name. Without it, the CLI uploads Dawn, Shopify's example theme, to the dev store. - Follow the CLI output to open the host theme in the theme editor.
- Add your app block to the theme, then save the theme.
- Open the preview URL printed at the bottom of the CLI output.
- 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.
- Run
shopify app deploy --config staging. - Test the change on a store that has the staging app installed.
- Run
shopify app deploy --config production --no-release. - Run
shopify app versions list --config productionto find the version name. - 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
--configand--allow-updates. In non-interactive runs, app deploy needs--allow-updates,--allow-deletesor--no-release. --allow-deleteskept 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-urlto link the commit to the app version in the Dev Dashboard.
shopify app deploy --config production --allow-updatesDeploy 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.


