Skip to content

Latest commit

 

History

History
316 lines (211 loc) · 7.47 KB

README.md

File metadata and controls

316 lines (211 loc) · 7.47 KB

EnvGuard Logo

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

NPM Version Downloads GitHub Stars License CI Status

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

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!

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

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