env-generator

Single source of truth for .env files across a monorepo.

Define all env vars in one env.json, organized by app, group, and environment. Run one command, get the right .env files everywhere.

Setup

npm install env-generator

Create an env.json in your project root (see env.template.json for the structure):

{
  "web": {
    "outputPath": "apps/web/.env",
    "database": {
      "local": {
        "DATABASE_URL": "postgresql://localhost:5432/myapp"
      },
      "staging": {
        "DATABASE_URL": "postgresql://staging-host:5432/myapp"
      },
      "prod": {
        "DATABASE_URL": ""
      }
    },
    "general": {
      "local": {
        "NODE_ENV": "development",
        "PORT": "3000"
      },
      "staging": {
        "NODE_ENV": "production",
        "PORT": "3000"
      },
      "prod": {
        "NODE_ENV": "production",
        "PORT": "3000"
      }
    }
  }
}

Each top-level key is an app. Inside each app, outputPath says where the .env file goes, and everything else is a "group" of related variables (database, auth, general, whatever makes sense for you). Each group has environments (local, staging, prod — or whatever you call yours).

Usage

# set everything to local
npx env-generator local

# set everything to staging
npx env-generator staging

# mix and match — local for everything, but staging for the cms
npx env-generator local --cms=staging

# interactive mode — pick environment per group with a nice UI
npx env-generator -i

# preview what would be generated without writing anything
npx env-generator local --dry-run

Profiles

If you find yourself repeatedly using the same combination of environments, create a profiles.json:

{
  "dev": {
    "description": "Local dev with staging CMS",
    "*": "local",
    "web": {
      "cms": "staging"
    }
  },
  "all-local": {
    "description": "Everything local",
    "*": "local"
  }
}

Then use them:

npx env-generator -p dev
npx env-generator -l         # list available profiles

Config location

By default it looks for env.json and profiles.json in the current directory. If your config lives somewhere else, use --config:

npx env-generator --config packages/env local

Output paths in env.json are always resolved from where you run the command (your project root), not from the config directory.

Secrets

Keep prod secrets out of version control. Put empty strings as placeholders in env.json for sensitive values — the tool will warn you about them. Fill them in locally or inject them in CI. You can also keep a separate env.json out of git and point to it with --config.