Themes & environments

shopify.theme.toml defines five environments: development, development-seed, staging, production and bootstrap. Set the store domains and theme IDs before first use.

shopify theme dev  -e development
shopify theme push -e production

The ignore list

Every environment ignores four things:

templates/*.json
templates/customers/*.json
sections/*.json          # section groups
config/settings_data.json

These belong to the merchant. The theme editor rewrites them whenever anyone adds a section or changes a setting, so pushing your copies would wipe their work.

development needs this too: shopify theme dev replaces the dev theme with your local files on every run, so without the ignore list every editor change is gone the next time you start.

The catch

Files nobody pushes are also files nobody initialises. A fresh theme has none of them, and fails in confusing ways:

npm run shopify:dev:seed does all three at once against a new theme. Use npm run shopify:bootstrap for a brand new store.

Going the other way, npm run shopify:pull brings editor changes back into src/ so you can commit them.

⚠️ Pushing settings_data.json overwrites everything the merchant set — fonts, colours, logo. Run npm run shopify:pull first if there's anything worth keeping.

⚠️ A misspelled -e is not an error. The CLI silently falls back to defaults, which means no ignore list. If a push starts asking which theme to overwrite, check your spelling.

Password-protected stores

Development stores are always password protected. Put the password in .env.local:

export SHOPIFY_FLAG_STORE_PASSWORD='your-storefront-password'

shopify:dev and shopify:console source it automatically. Nothing else needs it — push, pull and check go through the Admin API.

You can put store-password in shopify.theme.toml, but don't: that file is committed, and the CLI prints every value from it to your terminal on every run.