[TIPS] shopify.app.toml might be better to be gitignored and used for local development only

Tomoyuki_Kashiro · January 31, 2025, 8:36am

**From the perspective of .env **, it might be better to shopify.app.toml be used for local development only.

Remix app has a useful solution that .env is loaded automatically to override environment variables in local development.

on the other hand, shopify app deploy (without -c option) load .env by default.

github.com/Shopify/cli

packages/app/src/cli/constants.ts

589631d20


      
          export const configurationFileNames = {
            app: 'shopify.app.toml',
            web: 'shopify.web.toml',
            appEnvironments: 'shopify.environments.toml',
            lockFile: '.shopify.lock',
            hiddenConfig: 'project.json',
            hiddenFolder: '.shopify',
          } as const
          
          export const dotEnvFileNames = {
            production: '.env',
          }
          
          export const versions = {
            reactTypes: '17.0.30',
          } as const
          
          export const blocks = {
            extensions: {
              directoryName: 'extensions',
              defaultRegistrationLimit: 1,

This means…, there’s a possibility that you deploy extension which includes local environment variable to production unintentionally in the following situation.

use .env to override environment variables for local remix app
have extensions that use process.env.XXX which is defined in .env
deploy extensions to production using shopify app deploy in local machine

In this condition, production deploy command (shopify app deploy) running in local machine injects .env variables and deploys to production.

my solution

I use .env if I need and I make shopify.app.toml be gitignored for local development not to be used for production.

I also put a shopify.app.production.toml to link production shopify app setting and define environment variables in deploy server like github action then run deploy command for production like this.

$ shopify app deploy -c production

This solution prevents from leaking .env in production extensions.

Topic		Replies	Views
[Feature request] Document support for environment variables Extensions checkout-ui-ext	8	596	March 13, 2026
Managing shopify.app.toml and .env across multiple environments with Jenkins CI/CD And github Dev Platform app-deployment	2	92	March 18, 2026
Shopify App TOML file with Environment variables Shopify CLI and Libraries app-commands	3	974	March 21, 2025
Unclear messaging around and purpose of .env files Shopify CLI and Libraries app-commands	2	103	March 17, 2025
CLI tool for Environment Variables in Checkout Extensions Extensions checkout-ui-ext , pos-extensions , admin-ui-extensions , customer-account-ext	1	409	December 17, 2024

[TIPS] shopify.app.toml might be better to be gitignored and used for local development only

my solution

Related topics