How I stopped my team from breaking CI with missing .env variables

You probably know the feeling. You just finished a complex feature, added a new STRIPE_WEBHOOK_SECRET to your local .env file, committed the code, pushed it to GitHub, and went to grab a coffee feeling like a 10x developer.

15 minutes later, your Slack explodes:

"Hey, my local server is crashing, where do I get this Stripe key?"

Or worse, your CI/CD pipeline completely turns red. You forgot to update .env.example. Again.

This scenario was happening so often in my team that I decided to fix it at the root.

Why Runtime Validation Isn't Enough

You might be thinking: "Just use Zod or Joi to validate environments!"

And you absolutely should! But runtime validators only protect your app from booting with missing keys. They do not protect your team from human error. Zod can't force a developer to update the .env.example documentation before they push their branch.

I was tired of this documentation drift, so I built a lightweight CLI tool to solve it.

Enter env-rx 🩺

env-rx is a tiny tool that acts as a pre-flight check for your environment variables. It enforces perfect synchronization between your actual .env and your .env.example.

Instead of waiting for a runtime crash, you hook env-rx into your pre-commit process.

Whenever you try to git commit, env-rx analyzes your files. If it spots a new variable in your .env that is missing from .env.example, it blocks the commit and interactively helps you fix the mismatch right in your terminal. No more broken pipelines.

🚀 How to use it in 1 minute

You can run it manually anytime to diagnose your current setup:

npx env-rx

🛡️ The Ultimate Defense: CI/CD Pipeline Integration

Local Git hooks are great, but developers can always bypass them with --no-verify. To make your repository bulletproof, env-rx comes with a dedicated CI mode.

Just add this single step to your GitHub Actions (or GitLab CI) pipeline before the build step:

npx env-rx --ci

If it detects any mismatch between the dummy .env.example and the required keys, it will instantly fail the build with a clean, readable error log:

🩺 env-rx is analyzing your files...



⚠️ WARNING Mismatches found between your env files:



📍 Missing in .env.example (found in .env):

   + STRIPE_WEBHOOK_SECRET



✖ CI Check Failed: Environment variables are not synchronized.

Fail fast, fix fast. Your production environment remains pristine.

That's it! Zero configuration required. It just reads your existing files and ensures your team never wastes time hunting down missing keys again.

Try it out!

I'd love for you to try it out in your projects. Let me know what you think in the comments, or if you have any other cool tricks to keep environments in sync!

🔗 NPM: env-rx

🔗 GitHub: env-rx