https://github.com/arshtiwari2004/envguard
A zero-config, framework-agnostic NPM package that validates and documents your environment variables from your .env.example file, preventing runtime errors before they happen.
https://github.com/arshtiwari2004/envguard
acertinityui dotenv fs-extra jest-tests nextjs npm npm-cli npm-package yargs
Last synced: 3 months ago
JSON representation
A zero-config, framework-agnostic NPM package that validates and documents your environment variables from your .env.example file, preventing runtime errors before they happen.
- Host: GitHub
- URL: https://github.com/arshtiwari2004/envguard
- Owner: ArshTiwari2004
- Created: 2025-05-09T17:49:08.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-08T01:39:11.000Z (about 1 year ago)
- Last Synced: 2025-10-07T13:05:35.775Z (8 months ago)
- Topics: acertinityui, dotenv, fs-extra, jest-tests, nextjs, npm, npm-cli, npm-package, yargs
- Language: TypeScript
- Homepage: https://envguard.vercel.app
- Size: 1.05 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
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
```bash
npm install @arshtiwari/envguard
```
### Add to Project Startup
```bash
require('envguard'); // Validates env vars on startup
```
### Or Use CLI
```bash
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
```bash
npm install --save-dev @arshtiwari/envguard
# or
yarn add -D @arshtiwari/envguard
# or
pnpm add -D @arshtiwari/envguard
```
### 2. Validate in CLI
```bash
npx envguard validate
```
### 3. Use Programmatically
```bash
const { runEnvguard } = require('envguard');
if (!runEnvguard()) {
process.exit(1);
}
```
### 4. Access frontend
```bash
cd ui
npm install
npm run dev
```
Visit [http://localhost:5173](http://localhost:5173) to view the UI.
---
## Folder Structure
```bash
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
```bash
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:
```bash
# 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:
```bash
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](mailto:arshtiwari12345@gmail.com)
- **GitHub:** [@ArshTiwari2004](https://github.com/ArshTiwari2004)
- **Twitter/X:** [@ArshTiwari17](https://x.com/ArshTiwari17)
- **LinkedIn:** [Arsh Tiwari](https://www.linkedin.com/in/arsh-tiwari-072609284/)
For bug reports or feature requests, please [open an issue](https://github.com/ArshTiwari2004/envguard/issues) on GitHub.
---
Happy coding! May your environment variables always be valid. ✨