086 — EnvDiff

Date: 2026-08-10 Difficulty: ⭐⭐ (Easy-Medium) Estimated Build Time: 1.5 days Category: developer tools, utilities, devops

Problem

Developers frequently debug issues caused by mismatches between environment variable files — .env, .env.local, .env.staging, .env.production. A missing DATABASE_URL key, a typo in SMTP_HOST, or an extra DEBUG=true leaking into production can cause silent failures or security incidents.

Comparing .env files today means either diff on the command line (which treats every line as plain text and doesn't understand key=value structure) or visually scanning two files side-by-side. Neither option highlights:

1. Keys present in one file but missing in another — the most dangerous category (missing secrets = crashes).
2. Value differences between the same key across files.
3. Key ordering inconsistency that makes visual comparison harder.

There is no lightweight, client-side tool that parses .env semantics (key=value pairs, comments, blank lines, quoted values) and presents a structured diff between two files.

Core Features

P1 (MVP — Must-Have)

1. Two-Pane .env Upload/Paste — Left and right text areas where users paste or upload (drag-and-drop) two .env files.
2. Semantic Parser — Parse .env format correctly: skip # comments and blank lines, extract KEY=VALUE pairs, handle quoted values (KEY="val ue"), strip surrounding quotes for comparison.
3. Structured Diff View — After clicking "Compare", show a table with three columns:
   • Key name
   • Value in File A (or ✗ if missing)
   • Value in File B (or ✗ if missing) Rows color-coded: green = identical values, red = different values, orange = missing from one file.
4. Summary Bar — At the top: "X identical, Y different, Z missing from A, W missing from B" counts.
5. Filter/Search — Filter the diff table by: "All", "Different only", "Missing only". Plus a text search bar to find a specific key.
6. Copy Clean Diff — Export the diff table as a plain-text summary (suitable for pasting into Slack/pull requests) or as markdown.

P2 (Nice-to-Have, if time allows)

1. Value Masking — Detect likely secrets (keys matching *KEY*, *SECRET*, *TOKEN*, *PASSWORD*) and mask values with •••••• by default, with a "Show Values" toggle.
2. Key Sort — Sort both files alphabetically by key before comparing (toggle on/off).
3. Multi-File Compare — Support uploading 3+ .env files and showing a matrix view (key × files).

Target User

• Full-stack developers debugging environment mismatch issues across local/staging/production.
• DevOps engineers reviewing .env templates and actual deployments.
• Tech leads onboarding new team members (verify their .env.local matches the template).

Suggested Stack

• Framework: Next.js 15 (App Router) + TypeScript
• Styling: Tailwind CSS v4 + Shadcn/ui
• Parsing: Custom lightweight .env parser (no external lib needed — simple regex-based).
• State: React state (no backend/database needed — fully client-side).
• Testing: Vitest (unit tests for parser), Playwright (E2E for upload + compare flow).

Feasibility Gut-Check

Rescope Guidance (if deferred)

If deferred, likely reasons and rescope options:

• Over-engineering the multi-file matrix (P2.9) — drop it, stick to 2-file compare.
• Value masking complexity — make it optional P2, not P1.
• Keep the parser minimal: don't handle exotic .env features (multiline values, variable interpolation, export prefix). MVP parses standard KEY=VALUE + comments + blank lines only.

🧠 Brainstorm Review (2026-08-10)

Verdict: 🎨 Ready for Design — Total ≥ 12 and Market Fit ≥ 3. Promotes.

Architecture Design Spec

Status: ✅ Design Complete — Ready for implementation. Architecture document: designs/086-EnvDiff-architecture.md C4 Container diagram: diagrams/envdiff-architecture.html Designed by: System Architect | Date: 2026-08-12