Managing app configuration files
This guide shows you how to get started with Shopify CLI, manage and update app configurations, and safely test your app’s behavior.
What you'll learn
Anchor link to section titled "What you'll learn"After you've finished this tutorial, you'll understand:
- How to install Shopify CLI
- How to configure and manage Shopify apps from your terminal or IDE
- How to safely test and update your app configuration
Requirements
Anchor link to section titled "Requirements"- You've created a Partner account
- You've created a development store
- You've installed Node.js 16 or higher
Get started with the CLI
Anchor link to section titled "Get started with the CLI"Shopify CLI is a command-line interface tool that helps you build Shopify apps. It’s managed as a set of Node.js packages:
To enable a consistent development experience across environments, these packages should be added as dependencies of your app. If you can't add them as project-level dependencies, you can install Shopify CLI globally.
Or to install globally:
Link and configure apps
Anchor link to section titled "Link and configure apps"You can create, link, and configure Shopify apps directly from your preferred terminal or IDE using Shopify CLI. You can either create a new Shopify app or link to any existing apps. This generates a configuration file in the root directory of your app.
You can use your configuration file to view and modify your app’s configuration on Shopify. After you've made changes to your configuration file, you can run one of the following commands to push your changes up to Shopify, where they will go live immediately.
Learn more about the configuration file format.
Test your app functionality
Anchor link to section titled "Test your app functionality"After your app has been installed on a live store, avoid doing active development against it so that end-users are not affected by possible breaking changes. Shopify CLI makes this easy by allowing you to link multiple Shopify apps to your codebase, so that you can dedicate specific apps and their configurations for various development, staging, and production workflows.
Use shopify app config link
to generate additional configuration files for development or staging apps. You can also re-link upstream Shopify apps if your configuration file gets deleted, corrupted, or out-of-sync. If you already have a shopify.app.toml
in your root directory, then you’ll be prompted to give your configuration file a name, and a file shopify.app.{your-config-name}.toml
is generated in your root directory. Learn more about configuration names.
When you link to a Shopify app, it becomes your default configuration. This means that when you run shopify app dev
or other commands that reference a configuration file, your default configuration is selected. If you’d like to change your default configuration, then you can run shopify app config use
and pass in either your configuration name, or the file name:
You can also override your default configuration by passing a --config
flag to your command. This syntax can be used to leverage CLI behavior in scripts, CI/CD, or other automated processes:
Using different configuration files is a great way to quickly and safely test functionality across multiple apps and stores as your app grows in complexity.
Port changes across different app configurations
Anchor link to section titled "Port changes across different app configurations"Shopify configuration files make it easy to push and manage changes across development, staging, and production apps. After your configuration changes have been tested, you can copy and paste your blocks of configuration to any of your other configuration files, and push those changes up with shopify app config push --config {your_config}
.