.env.sample Guide

# Ignore actual env files .env .env.local .env.production .env.staging

The key is to make it obvious that these are not real credentials that will work out-of-the-box, but examples that must be replaced.

Several tools can help automate the creation and maintenance of your .env.sample file: .env.sample

A variable requires a highly specific format, such as a base64 encoded JSON string or a comma-separated list, but the sample file only provides an empty key name. The Solution: Always include a comment detailing the expected format or a link to the provider's documentation.

Create a file named .env.sample in the root directory of your project. Group variables logically, provide safe defaults where possible, and use clear placeholders for sensitive tokens. # Ignore actual env files

The major rule is that the actual .env file, which holds your real secrets, should be committed to version control. This is a critical security practice, as committing this file would expose all your credentials to anyone with access to the repository.

# .env.sample # Docker Configuration COMPOSE_PROJECT_NAME=myapp COMPOSE_FILE=docker-compose.yml Create a file named

Use comments to group related variables.

Manually adding, removing, or updating variables in both files is tedious and error-prone. Here are some excellent tools to automate the process:

For more complex projects, you may want multiple sample files:

A common debugging shortcut—logging process.env or $_ENV to console—can expose every secret in your application. If you must debug configuration, log only the specific variables you need, and redact sensitive values.