🛡️ EnvGuard – Validate & Secure Your Environment Variables

EnvGuard is an NPM package that validates your environment variables against a defined schema and enforces consistency with your .env.example file. Protect your application from misconfigurations and insecure defaults when working in teams or deploying to production.

Currently available on NPM: https://www.npmjs.com/package/@hoangsonw/env-guard

Table of Contents

• Features
• Installation
• Usage
  • Basic Usage
  • Advanced Usage
• API Reference
• Testing
• Building & Publishing
• Contributing
• License

Features

• Schema Validation: Define required environment variables and insecure default values.
• .env Enforcement: Compare your actual .env file against a provided .env.example file.
• Configurable Behavior: Choose whether to warn or throw errors, and control key matching.
• TypeScript Support: Fully written in TypeScript with complete type definitions.
• Cross-Platform: Works in Node.js and integrates seamlessly into your deployment workflows.

Installation

Prerequisites

• Node.js v14 or higher
• npm v6 or higher

Installing via NPM

npm install @hoangsonw/env-guard

Installing via Yarn

yarn add @hoangsonw/env-guard

Usage

EnvGuard validates your environment variables based on a schema. It loads variables from your .env file and compares them against a reference .env.example.

Basic Usage

Create a schema for your environment variables and validate:

import { validateEnv } from "@hoangsonw/env-guard";

const schema = {
  DB_HOST: { required: true, insecureValues: ["localhost", "127.0.0.1"] },
  DB_PASSWORD: { required: true, insecureValues: ["12345", "password"] },
  DB_USER: { required: false },
};

validateEnv({
  schema,
  envFilePath: "./.env", // Defaults to "./.env"
  exampleFilePath: "./.env.example", // Defaults to "./.env.example"
  allowMissingExampleKeys: false, // Warn if keys mismatch
  throwOnError: false, // Only warn; set to true to throw errors
});

Advanced Usage

You can customize EnvGuard’s behavior by changing options:

• allowMissingExampleKeys: When false, it warns if there are extra keys in your .env or missing keys compared to .env.example.
• throwOnError: When true, the function will throw errors instead of just logging warnings.

Example:

import { validateEnv } from "@hoangsonw/env-guard";

const schema = {
  API_KEY: { required: true },
  DB_HOST: { required: true, insecureValues: ["localhost"] },
  DB_PASSWORD: { required: true, insecureValues: ["password", "12345"] },
};

try {
  validateEnv({
    schema,
    envFilePath: "./config/.env",
    exampleFilePath: "./config/.env.example",
    allowMissingExampleKeys: false,
    throwOnError: true,
  });
  console.log("Environment variables validation passed!");
} catch (error) {
  console.error("Environment validation failed:", error);
  process.exit(1);
}

Note: The script might also parse environment variables from outside the .env file if they are already set in the environment of your machine or Node.js process. This can lead to some warnings in the console, if they are not defined in the .env.example file. You can safely ignore them.

API Reference

validateEnv(options: EnvGuardOptions): void

Parameters:

• schema: EnvSchema
  An object defining each environment variable’s requirements.
  Example:

  {
    DB_HOST: { required: true, insecureValues: ["localhost"] },
    API_KEY: { required: true }
  }

• envFilePath?: string
  Path to your .env file. Defaults to "./.env".

• exampleFilePath?: string
  Path to your .env.example file. Defaults to "./.env.example".

• allowMissingExampleKeys?: boolean
  If set to false, EnvGuard will warn about extra keys or missing keys between .env and .env.example.

• throwOnError?: boolean
  If true, the function will throw an error when validations fail; otherwise, it will only log warnings.

Returns:
Nothing; it performs validation and logs warnings/errors as configured.

Testing

EnvGuard includes a Jest test suite. To run tests:

1. Install dependencies:

   npm install

2. Run tests:

   npm test

Test files in the __tests__ directory demonstrate how EnvGuard validates environment variables and compares .env to .env.example.

Demo Scripts

Run the demo scripts in the __tests__ directory to see EnvGuard in action:

1. Run the demo script (with no basedir option):

   npm run demoNoBasedir

2. Run the demo script (with basedir option):

    npm run demoWithBasedir

The demo scripts will show how EnvGuard validates environment variables and compares .env to .env.example. Check the console output for validation results.

Building & Publishing

Building

Compile the TypeScript source:

npm run build

Publishing

1. Login to npm:

   npm login

2. Publish the package:

   npm publish --access public

Contributing

Contributions are welcome! Follow these steps:

1. Fork the Repository
2. Create a Feature Branch:

   git checkout -b feature/my-new-feature

3. Commit Your Changes
4. Submit a Pull Request

For major changes, please open an issue first to discuss your ideas.

License

This project is licensed under the MIT License.

Final Remarks

EnvGuard ensures your environment variables are correctly configured and secure, reducing misconfigurations in team settings and production deployments. With schema validation and .env.example enforcement, it helps maintain consistency and security in your projects.

Happy guarding! 🛡️