# Working with `shopify.app.toml` files  `shopify.app.toml` files are used to manage your Shopify 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 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 * Setting a `uri` for Shopify's compliance/GDPR webhooks requires deploying changes to the `shopify.app.toml` Only new Gadget apps will have managed TOML files. Existing Shopify apps will need to manually manage TOML files. ## The `shopify.app.toml` file  New Shopify apps on Gadget 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**: ```toml // in The default shopify.app.toml file # 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/advanced-topics/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..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: ```toml // in shopify..app.toml # Learn more about working with Shopify TOML files with Gadget at http://docs.gadget.dev/ client_id = "" name = "" application_url = "https://--.gadget.app/api/shopify/install-or-render" embedded = true [auth] redirect_urls = ["https://--.gadget.app/api/connections/auth/shopify/callback"] [webhooks] api_version = "2024-10" [[webhooks.subscriptions]] compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"] uri = "https://.gadget.app/api/webhooks/shopify" ``` Gadget will automatically provide the correct values for the required URL and ID fields. Previous versions of the `shopify.app.toml` file in your Gadget apps included `include_config_on_deploy = false`. This prevented TOML settings from being pushed to Shopify when `shopify app deploy` is run using Shopify CLI, such as when deploying Shopify extensions. This setting has been deprecated by Shopify. All changes in a TOML file will be pushed to Shopify whenever `shopify app deploy` is run. ### 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](https://docs.gadget-canary.xyz/guides/environments/deployment) 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 Shopify app using `ggt` and the Shopify CLI. 1. Install and use [Gadget's CLI, ggt](https://docs.gadget-canary.xyz/reference/ggt#install-ggt), to pull your project down to your local machine. 2. Install the [Shopify CLI](https://shopify.dev/docs/api/shopify-cli#installation) locally and use it to sign in to your Shopify Partners account. 3. Run the `yarn shopify:config:use:` command to specify the `shopify.app.toml` file that should be used for your Shopify app: ```sh # for development environment yarn shopify:config:use:development # for production environment yarn shopify:config:use:production ``` 4. Deploy your Shopify CLI app: ```sh yarn shopify:deploy:development # for production environment yarn shopify:deploy ``` 5. Connect to your existing Shopify app when prompted. ### Multiple connected Shopify apps  You need a separate `shopify.app.toml` file for each connected Shopify 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 Shopify 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: ```markdown // in example of toml files in a single app shopify.app.toml // for your production environment's Shopify 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](https://shopify.dev/docs/api/shopify-cli/app/app-config-use): ```bash // example of switching to the development environment yarn shopify:config:use:development ``` To see the current configuration, you can use the Shopify CLI's [`shopify app info` command](https://shopify.dev/docs/api/shopify-cli/app/app-info). ```bash // in get current configuration yarn shopify:info ``` ### Multiple production Shopify configurations  You have the option of adding multiple Shopify 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](https://shopify.dev/docs/apps/build/authentication-authorization/app-installation), 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](https://docs.gadget-canary.xyz/guides/plugins/shopify/advanced-topics/oauth#shopify-managed-installation-for-gadget-apps) with Gadget. ### Webhook subscriptions  Gadget manages [Shopify webhook subscriptions](https://docs.gadget-canary.xyz/guides/plugins/shopify/shopify-webhooks) for your Shopify applications, and does not support webhook subscription management in a `shopify.app.toml` file. You should not manually manage webhook subscriptions in the `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.