Files

In the project root folder, I typically maintain the following files:

  • .env.development: Default variables for local development; included in Git.
  • .env.development.local: Custom variables for local development; holdes secrets or overrides defaults in .env.development; not included in Git.
  • .env.sandbox: Default variables for the sandbox environment; included in Git.
  • .env.production: Default variables for production; included in Git.

If I need to build sandbox/production versions locally (which is typically not required as it’s handled by the CI/CD on a remote service), I would also have:

  • .env.sandbox.local: Not included in Git.
  • .env.production.local: Not included in Git.

Gitignore

In .gitignore, I exclude all local environment files:

# Environment variables
.env*.local

Structure of .env.development

Here’s the general structure I use for .env.development:

# Instructions for local development environment:
# 1. Create a new .env.development.local file in project root (git ignored).
# 2. Set there the variables that are missing values or that should override
#    the default defined here.
# 3. Do not include secrets in this .env.development file (which is included in
#    the repository).

PUBLIC_MIXPANEL_DEBUG=1
API_KEY=

As you can see, secrets like API_KEY are only placeholders (no value) since this file is included in the Git repository. Developers should add actual values to their local .env.development.local file (which is git ignored).

Usage

Here’s an example of how I use this environment variables structure:

In .env.development:

PUBLIC_MIXPANEL_DEBUG=1

In Mixpanel configuration file:

mixpanel.init('YOUR_TOKEN', {
	debug: import.meta.env.PUBLIC_MIXPANEL_DEBUG === '1',
})

The above code sets Mixpanel to debug mode by default in local development.

To disable debugging locally without affecting other developers, add the following to .env.development.local:

PUBLIC_MIXPANEL_DEBUG=0

This overrides the default value (in .env.development) only for the local machine (since .env*.local files are git ignrored).

References