env-example-diff

Keep .env and .env.example honest: parse dotenv format, diff two files for drift and leak risk, and generate a safe .env.example. Strict TypeScript, zero runtime dependencies.

Why

.env.example files rot silently — new keys get added to .env and never mirrored, and real secret values occasionally get copy-pasted into the example by mistake. This library catches both, plus a CI-friendly exit-code helper for a pre-commit or CI gate.

Quickstart

import { checkDrift } from "env-example-diff";
import { readFileSync } from "node:fs";

const result = checkDrift(
  readFileSync(".env", "utf8"),
  readFileSync(".env.example", "utf8")
);

console.log(result.summary);
process.exit(result.exitCode);

API

parseDotenv(text): DotenvEntry[]

Parses dotenv text: quoted/unquoted values, export prefix, comments (attached to the following entry), empty values.

diffEnvFiles(envText, exampleText): DiffResult

{ missingInExample, missingInEnv, emptyInEnv, valueLeakRisk } — arrays of keys.

looksLikeRealValue(value): boolean

The leak heuristic: length > 8, not an obvious placeholder (your..., <...>, changeme, xxx, etc.), not boolean/numeric.

generateExample(envText, options?)

Builds a .env.example from a real .env. options.style: "placeholder" (default, KEY=<key>) or "empty" (KEY=). Comments and export prefixes are preserved.

checkDrift(envText, exampleText)

Convenience wrapper for CI: { exitCode: 0 | 1, diff, summary }.

Limits

• looksLikeRealValue is a length/pattern heuristic, not a secret scanner — short secrets can be missed, and long-but-benign values (e.g. NODE_ENV=production at exactly 10 characters) can be flagged. Treat it as a prompt to review, not a guarantee.
• Multi-line values and .env files using shell variable expansion ($OTHER_VAR) are parsed as literal text, not expanded.

Part of the ferrow-toolkit collection · Sponsored by Ferrow