Skip to content
Mark Lavi edited this page Apr 30, 2024 · 14 revisions

My reasoning for a boilerplate .envrc, please adapt to your needs.

  1. Make .envrc operational; it should serve functional needs exclusively (as much as possible)
    • Corollary: set static values only in .env
  2. Make .env reproducible (as much as possible):
    • Do not commit it to revision control, because it can contains secrets
    • Recreate from a source (.env.sample) that omits secrets, but should be committed to revision control
    • Document and group similar variables
    • Lint syntax and other quality improvements

After years adopting direnv to manage scripts, configuration management, and containers with git, I evolved these practices:

  1. .gitignore .env, but commit .env{rc,.sample,*} files; see Git Tips
  2. Leverage two open source projects to accomplish .env documentation, creation, and linting:
    • Createnv: optionally prompt or create random secrets; good enough (despite limitations)
    • Dotenv Linter: configurable code standards
  3. rm .env when refactoring configuration with minimal problems
  4. Make the boilerplate unobtrusive, everything is triggered from establishing .env.sample
  5. Use the following .envrc boilerplate which add hints and references sources for learning:
# shellcheck shell=bash

# If .env missing; restore from .env.sample and validate
# See https://github.com/direnv/direnv/wiki/.envrc-Boilerplate
if [[ -f .env.sample ]]; then
  if ! command -v createnv > /dev/null; then
    echo 'WARN|Createnv missing; try: pyenv local 3.x && pip install createnv'
  elif [[ ! -f .env ]]; then
    createnv --use-default --overwrite \
      || echo 'ERROR|https://github.com/cuducos/createnv'
    if command dotenv-linter --version >&/dev/null; then
      dotenv-linter .env || echo 'ERROR|https://dotenv-linter.github.io'
    fi
  fi
fi

dotenv_if_exists || direnv status # https://direnv.net/man/direnv-stdlib.1.html

Additional background and optional bonus sections are on my blog.

Clone this wiki locally