A zero-config, framework-agnostic NPM package and UI for validating and documenting your environment variables, straight from your .env.example file.

---

Quick Start

Install via NPM

npm install @arshtiwari/envguard

Add to Project Startup

require('envguard'); // Validates env vars on startup

Or Use CLI

npx envguard validate

Features

• Zero-config - Works with existing .env.example
• Framework-agnostic - Node.js, Next.js, React, Vue, etc.
• Auto-documentation - Keep .env.example always updated
• Interactive UI - Visual debugger for environment variables
• Validation - Catch missing/invalid vars before runtime
• Multiple Integration Methods - CLI, programmatic, and React UI

---

🧰 Tech Stack

--

Category	Technologies
Backend/Core	TypeScript, Node.js
Schema Validation	Zod, Custom Schema Generator
File Parsing	dotenv, fs-extra
CLI	yargs, commander
Frontend (UI)	React.js, Vite , TailwindCSS
Testing	Jest
CI/CD	GitHub Actions

Installation and setup

1. Install

npm install --save-dev @arshtiwari/envguard
# or
yarn add -D @arshtiwari/envguard
# or
pnpm add -D @arshtiwari/envguard

2. Validate in CLI

npx envguard validate

3. Use Programmatically

const { runEnvguard } = require('envguard');
if (!runEnvguard()) {
process.exit(1);
}

4. Access frontend

cd ui
npm install
npm run dev

Visit http://localhost:5173 to view the UI.

---

Folder Structure

envguard/
├── .env.example                # Example env file for validation
├── .gitignore
├── README.md                   # Project documentation
├── package.json
├── babel.config.js             # Babel config for transpiling (if needed)
├── jest.config.js              # Jest config for tests
├── tsconfig.json               # TypeScript config (optional)
├── LICENSE
├── dist/                       # Transpiled output for npm (ignored in VCS)
│   └── ...                     # Compiled JS files
├── src/                        # Main source code
│   ├── index.js                # Main entry point (exports runEnvguard)
│   ├── parser/
│   │   └── envExampleParser.js
│   ├── schema/
│   │   └── schemaGenerator.js
│   ├── validator/
│   │   └── validator.js
│   ├── reporter/
│   │   └── errorReporter.js
│   ├── cli/
│   │   └── cli.js              # CLI entry point
│   ├── utils/
│   │   └── helpers.js
│   └── types/
│       └── index.d.ts          # Type definitions
├── server/                     # Backend server for live UI (optional)
│   └── server.js
├── scripts/                    # Utility scripts (e.g., generate .env.example)
│   └── generateEnvExample.js
├── tests/                      # Jest test files
│   ├── parser.test.js
│   ├── schema.test.js
│   ├── validator.test.js
│   └── cli.test.js
├── ui/                         # React UI dashboard (dev/optional)
│   ├── src/
│   │   ├── App.jsx
│   │   ├── main.jsx
│   │   ├── index.css
│   │   └── components/
│   │       └── EnvTable.jsx
│   ├── public/
│   │   ├── index.html
│   │   └── env-vars.json       # (for demo, replaced by API in prod)
│   ├── tailwind.config.js
│   └── vite.config.js
├── website/                    # Landing page (for npm promotion)
│   ├── src/
│   │   ├── App.jsx
│   │   ├── main.jsx
│   │   └── components/
│   │       ├── Hero.jsx
│   │       └── Pricing.jsx
│   ├── public/
│   │   └── index.html
│   ├── tailwind.config.js
│   └── vite.config.js

---

How It Works

1. Parse your .env.example for variable names and defaults.
2. Generate a validation schema automatically.
3. Validate your actual environment (process.env) against the schema.
4. Report errors in CLI, programmatically, or visually in the UI.

---

File Structure Example

project-root/
├── .env                # Local environment (gitignored)
├── .env.example        # Template with all required vars
├── .env.development    # Environment-specific vars
├── .env.production
└── package.json

Your .env.example should look like:

# Required variables
API_KEY=your_api_key_here
DATABASE_URL=postgres://user:pass@localhost:5432/db

# Optional variables
# PORT=3000
# DEBUG=false

Advanced Configuration

Create envguard.config.js for custom rules:

module.exports = {
  // Custom schema rules
  rules: {
    API_KEY: {
      minLength: 32,
      pattern: /^sk_[a-zA-Z0-9]+$/
    }
  },
  
  // Additional environments
  environments: ['staging', 'test'],
  
  // Custom error messages
  messages: {
    missing: '🚨 Missing required env var: {var}',
    invalid: '❌ Invalid value for {var}: {error}'
  }
};

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

---

License

MIT © Arsh Tiwari

---

📬 Contact

Have questions or need help? Feel free to reach out!

• Email: arshtiwari12345@gmail.com
• GitHub: @ArshTiwari2004
• Twitter/X: @ArshTiwari17
• LinkedIn: Arsh Tiwari

For bug reports or feature requests, please open an issue on GitHub.

---

Happy coding! May your environment variables always be valid. ✨