DEV Community

Isaac
Isaac

Posted on

Your .env file is a mess (and how to fix it in 2 seconds)

#opensource #webdev #javascript #typescript

If you've been working on a project for a while, your environment variables are probably a mess.

We've all been there:

  • Your .env file has 30 variables, but half of them are left over from features you deleted last year.
  • A new developer joins the team, clones the repo, and spends half a day trying to figure out why the app won't boot because the .env.example file hasn't been updated since 2023.
  • Worse: someone accidentally put a sensitive API key behind a NEXT_PUBLIC_ or VITE_ prefix, and you just shipped it to the browser.

Environment variables are the backbone of modern web apps, but we manage them like it's 2014—by manually copying and pasting keys between files and hoping we didn't forget anything.

I got tired of this, so I built a tool to fix it.

Meet Pookoo 🦉

Pookoo is a zero-config, static analysis CLI that audits, documents, and manages your environment variables automatically.

You don't need to install it to try it. Just run this in the root of any JS/TS project:

npx pookoo scan .
Enter fullscreen mode Exit fullscreen mode

In less than a second, Pookoo reads your source code (using AST parsing, so it never executes your code and never sends data anywhere) and gives you a report of everything that is broken.

Pookoo Scan CLI Output

What it detects:

  • Dead variables: Keys in your .env that are never actually referenced in your source code.
  • Undocumented variables: Keys used in your source code (process.env.SOMETHING) that are missing from your .env.example.
  • Secret leaks: Sensitive keys (like STRIPE_SECRET_KEY) that are accidentally exposed via client-side prefixes.
  • Inconsistent defaults: The same variable using different hardcoded fallbacks across different files.

Generating .env.example automatically

The best part about Pookoo knowing exactly what variables your code uses? It can write your .env.example for you.

npx pookoo init .
Enter fullscreen mode Exit fullscreen mode

This command scans your codebase, finds every single environment variable you are actually using, and generates a perfectly categorized .env.example file. It even adds comments telling you exactly which files are using which variables.

Pookoo generated env.example

Generating Documentation

If you work on a larger team, you can generate a beautiful markdown reference of your entire configuration surface:

npx pookoo docs .
Enter fullscreen mode Exit fullscreen mode

This creates a CONFIG_DOCS.md file with a table of every variable, its scope (Client vs Server), and where it's used.

Try it out

Pookoo supports Next.js, Vite, Create React App, Node.js, and generic TypeScript projects out of the box.

If you want to keep your project clean permanently, you can even add it to your CI/CD pipeline to fail the build if someone forgets to document a new variable:

pookoo scan . --fail-on HIGH
Enter fullscreen mode Exit fullscreen mode

I'd love for you to try it on one of your messy projects and let me know how many dead variables it finds!

Let me know what you think in the comments! 👇

Top comments (0)