envfix

Product Introduction

1. Definition: envfix is a zero-dependency, command-line interface (CLI) tool designed for Node.js and JavaScript development environments. It functions as an automated environment configuration doctor and fixer, specifically engineered to manage, validate, and synchronize .env and .env.example files.
2. Core Value Proposition: It exists to eliminate environment variable drift, configuration errors, and security risks in software projects. Its primary value is providing immediate, actionable diagnostics and automated fixes for environment configuration, ensuring development, staging, and production environments remain consistent and secure without manual intervention.

Main Features

1. Environment Configuration Validation: The tool performs a deep, syntax-aware comparison between a live .env file and its corresponding .env.example template. It detects missing variables, empty values, extra variables not defined in the template, and duplicate declarations. It parses dotenv syntax, handling quoted values, inline comments, and multiline strings to catch malformed declarations that could cause silent failures.
2. Automated Correction and Synchronization: The envfix fix command can automatically append missing environment variables to the .env file, preserving all existing values and file structure. The envfix example command generates a sanitized .env.example file from a live .env, stripping values to prevent secret leakage. The --sync flag intelligently updates the example file by appending new keys and reporting stale ones.
3. Comprehensive Health Check (doctor): This command executes a full diagnostic suite beyond simple comparison. It checks for file existence, validates syntax integrity, assesses consistency between files, and performs Git safety audits. It verifies that the .env file is both untracked by Git and correctly listed in .gitignore, identifying critical security oversights.
4. CI/CD and Automation Native: Designed for seamless integration into Continuous Integration and Continuous Deployment pipelines. It provides machine-readable JSON output (--json) and generates GitHub Actions workflow command annotations automatically when run in a CI context. Meaningful exit codes (0 for success, 1 for problems, 2 for errors) allow it to fail builds proactively when configuration drift is detected.
5. Multi-Environment and Bulk Analysis: Supports custom file paths via --env and --example flags for any naming convention (e.g., .env.production). The --all flag performs a bulk scan of the directory, identifying all .env*.example file pairs and checking each against its corresponding environment file in a single command, ideal for monorepos or projects with multiple configurations.

Problems Solved

1. Pain Point: "It works on my machine" syndrome caused by environment variable mismatches. Developers waste significant time debugging application crashes that stem from missing, empty, or misspelled environment variables after pulling new code or onboarding to a project.
2. Target Audience: Node.js and full-stack JavaScript developers, DevOps engineers, and engineering team leads. It is particularly valuable for open-source contributors, remote development teams, and organizations enforcing strict security and configuration compliance across microservices.
3. Use Cases: Essential for pre-commit hooks or CI pipeline steps to prevent configuration drift from being merged. Critical for onboarding new developers to a project to instantly configure their local environment. Used by lead developers to audit project configuration health and enforce template compliance. Vital for generating safe, up-to-date example files for public repositories without risking secret exposure.

Unique Advantages

1. Differentiation: Unlike basic dotenv libraries or manual diffing, envfix is a proactive diagnostic and remediation tool. Compared to other env checkers, its append-only fixing philosophy guarantees it will never overwrite or corrupt existing configuration values. Its deep Git safety check goes beyond a simple .gitignore lookup to confirm the file is not already tracked in version history.
2. Key Innovation: Its zero-dependency architecture makes it incredibly lightweight, secure, and instantly executable via npx. The combination of bulk pair analysis (--all) and CI-native features (annotations, JSON output) in a single, dependency-free package is unique. The --fill-empty --copy-values logic demonstrates sophisticated value handling, ensuring correct parsing and round-trip integrity when populating empty variables from an example file.

Frequently Asked Questions (FAQ)

1. How does envfix handle secrets and prevent accidental exposure? envfix is designed with security-first principles. The example command automatically omits all values when generating an .env.example file. The fix command masks copied values in terminal output as <copied>. It includes built-in Git safety checks to warn if your .env file is tracked or unignored, a major security risk.
2. Can envfix be used in a CI/CD pipeline like GitHub Actions? Yes, envfix is built for CI/CD. It auto-detects GitHub Actions runners and outputs workflow command annotations, highlighting issues directly in the pull request interface. Its configurable exit codes allow it to fail a build step when missing variables or configuration errors are detected, enforcing compliance.
3. What happens if I run envfix fix? Will it change my existing environment values? No. The fix command is strictly append-only. It only adds new lines for variables that are missing from your .env file. It will never modify, delete, or overwrite any existing line or value in your file, ensuring your current configuration remains completely intact.
4. Does envfix support projects with multiple environment files (e.g., .env.development, .env.test)? Absolutely. You can use the --env and --example flags to specify any file pair. Furthermore, the --all flag will automatically discover and validate all pairs of files in your directory that match the pattern .env*.example, making it perfect for projects with complex, multi-environment setups.
5. Is envfix only for Node.js projects? While built with Node.js and optimized for its ecosystem (distributed via npm), envfix operates on standard .env file formats. It can be used to manage environment configuration for any project or technology stack that uses .env files, including Docker, Python, PHP, or Go applications, by simply running it via npx in the project directory.