@ibnushahraa/vite-plugin-dotenv-guard

🔐 Vite plugin for dotenv-guard - load and validate environment variables with auto-mode detection.

✨ Features

• 🔄 Auto Mode Detection → Automatically loads .env.{mode} based on Vite mode
• 🔒 Encryption Support → Auto-decrypts encrypted values (AES-256-GCM)
• 🎯 Selective Encryption → Config-based encryption via env.enc.json
• ✅ Schema Validation → Enforce required keys, regex patterns, enums (same as core)
• ⚡ Zero Config → Works out of the box with Vite modes
• 🎯 Type-Safe → Full TypeScript support
• 📦 Zero Native Deps → Built-in crypto, no keytar required

📦 Installation

npm install @ibnushahraa/vite-plugin-dotenv-guard

🚀 Usage

Basic Setup

// vite.config.js
import { defineConfig } from 'vite';
import dotenvGuard from '@ibnushahraa/vite-plugin-dotenv-guard';

export default defineConfig({
  plugins: [
    dotenvGuard()
  ]
});

This automatically loads:

• .env.development → when running npm run dev (development mode)
• .env.production → when running npm run build (production mode)
• .env.{custom} → when running vite --mode custom

With Schema Validation

Create env.schema.json:

{
  "VITE_API_URL": {
    "required": true,
    "regex": "^https?://"
  },
  "VITE_API_KEY": {
    "required": true
  },
  "VITE_ENV": {
    "required": true,
    "enum": ["development", "staging", "production"]
  }
}

Enable validator:

// vite.config.js
import dotenvGuard from '@ibnushahraa/vite-plugin-dotenv-guard';

export default defineConfig({
  plugins: [
    dotenvGuard({
      validator: true
    })
  ]
});

If validation fails, build/dev server will exit with error details.

⚙️ Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | path | string | undefined | Custom .env file path (auto-detects .env.{mode} if not set) | | validator | boolean | false | Enable schema validation | | schema | string | 'env.schema.json' | Schema file path |

Note: Encryption is always enabled. Plugin auto-decrypts encrypted values at build-time (read-only, no file modification).

📚 Examples

With Validation

dotenvGuard({
  validator: true
})

Note:

• Encryption is always enabled (auto-decrypts encrypted values)
• Selective encryption is configured via CLI: npx dotenv-guard init enc
• To use plaintext .env, run: npx dotenv-guard decrypt first

Custom Schema Path

dotenvGuard({
  validator: true,
  schema: 'config/env.schema.json'
})

Custom File Path

dotenvGuard({
  path: '.env.custom',
  validator: true
})

TypeScript

// vite.config.ts
import { defineConfig } from 'vite';
import dotenvGuard from '@ibnushahraa/vite-plugin-dotenv-guard';

export default defineConfig({
  plugins: [
    dotenvGuard({
      validator: true,
      schema: 'env.schema.json'
    })
  ]
});

📋 Schema Validation Rules

Same format as core package:

{
  "VARIABLE_NAME": {
    "required": true,        // Boolean (default: true)
    "regex": "^pattern$",    // String regex pattern
    "enum": ["val1", "val2"] // Array of allowed values
  }
}

Example:

{
  "VITE_API_URL": {
    "required": true,
    "regex": "^https?://.*"
  },
  "VITE_LOG_LEVEL": {
    "required": false,
    "enum": ["debug", "info", "warn", "error"]
  }
}

🔄 Mode Detection

Plugin automatically detects Vite mode:

npm run dev              # Loads .env.development
npm run build            # Loads .env.production
vite --mode staging      # Loads .env.staging

🆚 Comparison

❌ Without Plugin

// Manual dotenv loading
import dotenv from 'dotenv';
dotenv.config({ path: `.env.${process.env.NODE_ENV}` });

export default defineConfig({
  // ... config
});

✅ With Plugin

import dotenvGuard from '@ibnushahraa/vite-plugin-dotenv-guard';

export default defineConfig({
  plugins: [dotenvGuard({ validator: true })]
});

🛡️ Best Practices

• ✅ Use VITE_ prefix for client-side variables
• ✅ Keep .env.local and .env.*.local in .gitignore
• ✅ Commit .env.development and .env.production templates
• ✅ Enable validator: true to catch missing variables early

⚠️ Important Notes

• Auto-Decryption: Always enabled, auto-decrypts encrypted values using AES-256-GCM (via core package)
• Selective Encryption: Configure via npx dotenv-guard init enc (creates env.enc.json)
• Read-Only: Plugin only decrypts at build-time, never modifies .env files
• Master Key: Encryption key stored in ~/.dotenv-guard/master.key (auto-generated)
• Vite-Only: Designed specifically for Vite. For other build tools, use @ibnushahraa/dotenv-guard

📖 Related

• Core Package: @ibnushahraa/dotenv-guard (with encryption support)
• Monorepo: dotenv-guard

📄 License

MIT © 2025