Most of what I write about dotguard is about catching secrets — the scary stuff, the leaked keys, the red builds. But the check I rely on most in day-to-day work is the least scary one in the tool: it flags env files that are missing variables a healthy app is expected to define.
Specifically, it checks for NODE_ENV and PORT. Two variables. And they have caused more real breakage in my projects than any secret leak.
Why these two
NODE_ENV is the switch that decides a huge amount of runtime behavior: which logging level, whether minification happens, whether certain middleware loads, whether a dev server starts. When it's missing, the app doesn't fail loudly — it falls into whatever the library's default is, which is usually development. A "production" deploy running in development mode is a quiet, expensive bug: verbose logs, no caching, debug endpoints live, and in some frameworks, different security defaults.
PORT is the one that kills deploys. The app starts, the container health check fails because it's listening on 3000 while the platform expects 8080, the deploy rolls back, the on-call gets paged at 2am, and the fix is a one-line env variable that should have been in the example file from day one.
Both failures have the same signature: the variable wasn't set anywhere, nothing complained, and the app did something reasonable-but-wrong.
What the check looks like
dotguard reads each env file, collects the variable names it defines, and reports anything from its small expectation list that's absent:
$ npx @wuchunjie/dotguard .
.env (1 issue)
L 0 | Missing NODE_ENV
Consider adding: NODE_ENV=production
0 potential secrets exposed!
Note the type: this is an info finding, not a warning. The tool deliberately doesn't fail the build on a missing variable the way it does on a suspected secret — because a missing NODE_ENV in a local dev env file is normal and fine. The value of the check isn't the failure; it's that the finding shows up in the report, and the report is what you read before you deploy.
How I actually use it
Three habits, all cheap:
1. Before any deploy. npx @wuchunjie/dotguard . is the first command I run against the target environment's config. If the production env file is missing NODE_ENV=production, that's the deploy blocker, caught in two seconds instead of discovered in the logs an hour later.
2. When onboarding a service. A new service's env file that passes the missing-variable check is a strong signal it's complete enough to trust. It's not proof — the check list is deliberately small — but it's a fast first filter that catches the "forgot the basics" class.
3. As the example-file test. The committed .env.example should pass the check cleanly. If your own example file is missing NODE_ENV or PORT, every developer copying it inherits the gap. The example file is the contract; the scanner is the contract test.
Why not just lint the app code for process.env usage?
You can — parse the source for every process.env.X read and diff against the defined variables. It's a better check, and I've done it as a script. But it has two problems in practice:
- It's app-specific. Every service needs its own version, and the "what does this app read" list drifts as the code changes.
- It's slow to set up relative to the value. The two-variable check in dotguard catches 80% of the "obvious missing basics" breakage with zero per-app configuration.
The full diff is a good next step for a service that's had a NODE_ENV incident. The two-variable check is the good first step for every service.
The meta-lesson
The most valuable checks in a tool are often the boring ones. The secret patterns get the blog posts; the missing-variable note is what I actually run every day, because the failures it prevents are the ones that are common, cheap to cause, and expensive to find in production.
Small check, big time savings. Run it before the deploy, not after the page.
npx @wuchunjie/dotguard
More Tools
| Tool | What it does | Command |
|---|---|---|
| scaffoldx-cli | Production-ready project templates in seconds | npx scaffoldx-cli |
| dotguard | Scan .env files for exposed secrets | npx @wuchunjie/dotguard |
| gitpulse | Git repo analytics in your terminal | npx @wuchunjie/gitpulse |
| snippetx | Terminal code snippet manager | npx @wuchunjie/snippetx |
If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.
Top comments (0)