envtainer

Manage your environment variables across projects and environments — keep .env files organized, validated, and in sync.

Features

• Manage environment variables across multiple environments (development, staging, production)
• Validate required variables and types before your app starts
• Sync .env templates across team members
• Diff and merge environment files safely

Usage

# Initialize envtainer in your project
envtainer init

# Validate current .env against .env.example
envtainer validate

# Show diff between environments
envtainer diff development production

Use Cases

• Ensure required env vars are set before deployment
• Keep team .env files in sync with a template
• Prevent secrets from leaking into version control
• Manage per-environment configuration

The Environment Management Workflow

envtainer treats environment configuration as a managed artifact with a template, a validation step, and a diff — instead of a pile of files everyone edits by hand.

1. Initialize. envtainer init creates the baseline: a committed template that lists every variable the project expects, with non-secret defaults where possible. The template is safe to commit because it holds keys, not values.

envtainer init
# creates .env.example (committed) and a local .env (ignored)

2. Validate before the app starts. envtainer validate checks the local .env against the template: required keys present, no unknown keys, and values that match declared types (string, number, boolean, URL). Run it in a predev or prestart script so a misconfigured environment fails immediately, not halfway through a request.

envtainer validate
# ✗ Missing: DATABASE_URL
# ✗ Invalid type: PORT should be a number

3. Diff across environments. envtainer diff development production shows exactly which variables differ between two environment files. This is the check that prevents the classic “works on staging, breaks in production” bug caused by a renamed key.

4. Sync the team. New variables enter the project through the committed template. A teammate pulls, runs envtainer validate, and immediately sees what their local .env is missing, without anyone pasting secret values into chat.

Why Validate Environment Variables at All

Most runtime failures caused by configuration are silent until the worst moment: a missing key returns undefined, an unparsed PORT binds to NaN, and a malformed URL throws deep inside a connection pool. Validation turns all of those into one loud, early, readable error. The earlier the failure, the cheaper the fix.

envtainer vs. Node dotenv Tooling

Tool	Focus	Validation	Multi-environment diff	Template sync
envtainer	Management + validation	Yes, typed required keys	Yes (diff a b)	Yes, committed template
dotenv	Loading .env into process.env	No	No	No
dotenv-safe	dotenv + required-key check	Yes (required keys)	No	Partial, via example file
direnv	Per-directory env loading in the shell	No (shell logic)	No	No

dotenv is a loader; envtainer is a manager. Many projects keep dotenv for the actual process.env injection at runtime and use envtainer ahead of it to guarantee the file it loads is complete and well-typed. dotenv-safe overlaps on required-key checking but stops there — it does not diff environments or declare types.

FAQ

Is .env committed? No. Only the template (.env.example) is committed. Real values stay local and ignored.

Does envtainer store secrets? No. It manages structure and validation; it does not become a secrets vault.

Can it fail my build? Yes — run envtainer validate in CI or a prestart script and treat a non-zero exit as a failed run.

How is this different from dotenv-safe? dotenv-safe checks that required keys exist. envtainer also validates types, diffs environments, and keeps a syncable template.

What happens if a teammate adds a key? They add it to the committed template. Everyone else sees it on their next envtainer validate.

Related Tools

• secretsweep — scan staged files so a real .env never gets committed.
• gitcommitgen — write the commit message when you update the template.
• jsonask — inspect JSON config files that mirror environment settings.
• Browse the rest of the developer tools collection and the collection announcement.