Abin GenEnv

A smart environment variable safety system for Node.js projects. Automatically scans your codebase for environment variables, validates runtime expectations, and generates reports so apps never fail because of missing config.

Features

• 🔍 AST-based scanning: Safely detects process.env.VAR, process.env["VAR"], and import.meta.env.VAR usage
• 📝 Smart generation: Groups variables by category and provides intelligent default values
• 🎯 Framework support: Automatic detection for Next.js, Vite, and Nuxt.js public variables
• 🛡️ Safe defaults: Never overwrites existing .env files
• 🎨 Pretty CLI: Colorful output with progress indicators
• 📦 Zero-config: Works out of the box with sensible defaults

Installation

npm install -g abin-genenv
# or
npx abin-genenv

Usage

Basic Usage

Scan your project and generate .env.example:

npx abin-genenv
# or
abin-genenv scan

Advanced Options

# Generate .env file (only if it doesn't exist)
npx abin-genenv --write-env

# Specify framework for better categorization
npx abin-genenv --framework nextjs

# Output detected variables as JSON
npx abin-genenv --json

# Check for missing environment variables and fail CI if absent
npx abin-genenv --check

# Validate env variables against code usage (explicit command)
npx abin-genenv validate

# Guard at runtime and fail fast with clear error
npx abin-genenv guard

# Generate env health report (JSON or HTML)
npx abin-genenv report --format json --output env-report.json

# Validate env file from custom path
npx abin-genenv validate --env-file .env.production

CLI Options

| Option | Description | |--------|-------------| | --write-env | Create .env file if it doesn't exist | | --framework <type> | Framework type: nextjs, vite, nuxt | | --json | Output detected variables as JSON | | --check | Exit with error if any env vars are missing | | --env-file <path> | Customize .env path for validation commands | | --format <json|html> | Report output format for report command | | --output <file> | Output file path for report command |

Example Output

🔍 Scanning for environment variables...
✅ Found 8 environment variables

📁 SERVER:
  • PORT
  • NODE_ENV

📁 DATABASE:
  • DATABASE_URL
  • DB_HOST

📁 SECURITY:
  • JWT_SECRET

📁 FRONTEND/PUBLIC:
  • NEXT_PUBLIC_API_URL

✅ Generated .env.example

Generated .env.example

# Environment Variables
# Generated by abin-genenv

# SERVER
PORT=3000
# Port for the server to listen on
NODE_ENV=development
# Environment (development, production, test)

# DATABASE
DATABASE_URL=postgresql://localhost:5432/mydb
# Database connection string
DB_HOST=localhost

# SECURITY
JWT_SECRET=your-secret-key
# Secret key for JWT tokens

# FRONTEND/PUBLIC
NEXT_PUBLIC_API_URL=http://localhost:3000

API Usage

You can also use abin-genenv programmatically:

import { scanEnvVariables, generateEnvExample } from 'abin-genenv';

const variables = await scanEnvVariables({
  framework: 'nextjs',
  includePatterns: ['src/**/*.{js,ts,jsx,tsx}'],
  excludePatterns: ['node_modules/**']
});

generateEnvExample(variables);

How It Works

1. Scanning: Uses TypeScript compiler API to parse source files and detect environment variable access patterns
2. Categorization: Groups variables by type (server, database, security, etc.) and framework-specific prefixes
3. Generation: Creates .env.example with smart defaults and helpful comments
4. Safety: Never overwrites existing files, provides clear feedback

Supported Patterns

• process.env.VARIABLE_NAME
• process.env["VARIABLE_NAME"]
• import.meta.env.VARIABLE_NAME (for Vite, etc.)

GitHub Actions / CI Integration

Add a workflow in .github/workflows/env-check.yml to fail builds when env vars are undefined:

name: Env Validation

on:
  push:
    branches: [main]
  pull_request:

jobs:
  validate-env:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm ci
      - name: Run env validation
        run: npx abin-genenv validate --check

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT