Working with shopify.app.toml files 

shopify.app.toml files are used to manage your Shopify Partner app configuration settings. This is useful when building apps using Shopify's CLI.

Gadget will automatically create and manage shopify.app.toml files for Shopify Partners apps.

You do not need to manually edit these TOML files in Gadget unless you are doing one of the following:

• A shopify.app.toml file is used to set up Shopify-managed app installs
• A shopify.app.toml is required when building and deploying Shopify extensions

The shopify.app.toml file 

New Shopify apps on Gadget will include a shopify.app.toml file in the root of the project.

This file will be for your production environment.

By default, this file will only contain comments and the file does not need to be modified:

The default shopify.app.toml file
toml
Copy
# This toml file is used for production. Only edit this file if you have a need for it
# When you add a production config, values will be auto-populated here
# Read more at https://docs.gadget.dev/guides/plugins/shopify/shopify-app-toml

Gadget will automatically update this production TOML file when a Shopify connection configuration is set in your production environment.

Development environment shopify.app.toml files 

Additional shopify.app.<ENVIRONMENT>.toml files will be automatically added to your app when you add a new Shopify connection configuration in Gadget, and will look similar to this:

shopify.<ENVIRONMENT>.app.toml
toml
Copy
1# Learn more about working with Shopify TOML files with Gadget at http://docs.gadget.dev/
2
3client_id = "<SHOPIFY-CLIENT-ID>"
4name = "<YOUR-APP-NAME>"
5application_url = "https://<YOUR-APP-SLUG>--<ENVIRONMENT>.gadget.app/api/shopify/install-or-render"
6embedded = true
7
8[build]
9# Gadget manages all your scopes, webhooks and api versioning for your app
10# As such, this line should not be changed unless you are working with
11# Shopify managed installations. Read more at http://docs.gadget.dev/
12include_config_on_deploy = false
13
14[auth]
15redirect_urls = ["https://<YOUR-APP-SLUG>--<ENVIRONMENT>.gadget.app/api/connections/auth/shopify/callback"]
16
17[webhooks]
18api_version = "2024-10"

Gadget will automatically provide the correct values for the required URL and ID fields.

Deploying without Shopify extensions or Shopify-managed installs 

If you are not making use of any Shopify extensions for your app and aren't setting up Shopify-managed installs, you can safely ignore the added shopify.app.toml files. This means you can continue to deploy to production using ggt or the Gadget editor.

Connecting a shopify.app.toml file to a Shopify app 

By default, Gadget will manage shopify.app.toml files and you will not need to interact with them.

If you are building Shopify extensions for your app, you will need to connect the correct shopify.app.toml to your Partners app using ggt and the Shopify CLI.

1. Install and use Gadget's CLI, ggt, to pull your project down to your local machine.
2. Install the Shopify CLI locally and use it to sign in to your Shopify Partners account.
3. Run the shopify app config use command to specify the shopify.app.toml file that should be used for your Partners app:

terminal
Copy
shopify app config use shopify.app.<ENVIRONMENT>.toml

4. Update include_config_on_deploy to true in your TOML file:

shopify.app.<ENVIRONMENT>.toml
toml
Copy
[build]
include_config_on_deploy = true

5. Deploy your Shopify CLI app:

terminal
Copy
shopify app deploy

6. Connect to your existing Partners app when prompted.

Multiple connected Partners apps 

You need a separate shopify.app.toml file for each connected Partners app.

This means that if you are working on an app as a team, you will have multiple shopify.app.toml files in your project, each with the configuration settings for a different Partners app, and a separate toml file for your production app.

This usually means that you have a separate toml file for each development environment in your project.

For example, you may have the following shopify.app.toml files in a single app:

example of toml files in a single app
Copy
shopify.app.toml // for your production environment's Partner app

shopify.app.development.toml // for your development environment
shopify.app.development-2.toml // a second app connected to the development environment
shopify.app.carl-dev.toml // for a carl-dev development environment

To switch between configurations while building, you can use the Shopify CLI's shopify app config use command:

example of switching to a new configuration
Copy
shopify app config use

To see the current configuration, you can use the Shopify CLI's shopify app info command.

get current configuration
Copy
shopify app info

Multiple production Shopify configurations 

You have the option of adding multiple Shopify Partners app configs to your production environment.

Gadget will not automatically create TOML files for additional connection configurations added to the production environment. You need to create these TOML files manually.

Setting up Shopify-managed app installs 

Gadget apps support Shopify-managed installations, which improve performance by removing the browser redirects normally required during app installation.

Read our guide to learn how to set up Shopify-managed app installs with Gadget.

Webhook subscriptions 

Gadget manages Shopify webhook subscriptions for your Shopify applications, and does not support webhook subscription management in a shopify.app.toml file.

Webhook filtering 

Gadget does not support webhook filtering in the shopify.app.toml file.

Support for Shopify webhook filtering in Gadget is currently in development.