Env Preflight 🛡️✈️

Simple, framework-agnostic SDK for validating required environment variables in Node.js apps. Keep configs clean, fail fast with friendly, well-formatted logs.

What Env Preflight solves

You ship a service that runs perfectly locally and on staging, but production crashes or—worse—behaves unpredictably because:

• A required variable (like DATABASE_URL) wasn’t set in the production/local/staging environment
• PORT was set to "eighty" instead of a number
• ADMIN_EMAIL had a typo
• BASE_URL missed its protocol and broke redirects
• New feature depends on a fresh env var; a team mate forgot to include it in prod environment. All quiet at boot… then the first request hits that path and kaboom — hello 500s.

Env Preflight performs a quick preflight at startup, validating the presence and basic types of the environment variables your app relies on. When something’s off, it prints a clear, friendly report and (optionally) exits fast so you don’t ship broken configs. This saves hours of debugging and prevents subtle runtime bugs caused by misconfigured environments in local dev, CI, and production.

Features

• Zero coupling to dotenv (or any loader) – you bring envs, Env Preflight validates
• Simple rules: 'string' | 'number' | 'boolean' | 'url' | 'email'
• Clean output with minimal color (or plain mode)
• Fail-fast option to exit process on invalid/missing envs
• Tiny surface area and TypeScript types out of the box

Installation

npm install env-preflight
# or
yarn add env-preflight
# or
pnpm add env-preflight

Quick Start (TypeScript)

import { EnvGuard, EnvGuardConfig } from "env-preflight";

const config: EnvGuardConfig = {
  required: {
    API_KEY: "string",
    PORT: "number",
    DATABASE_URL: "url",
    ADMIN_EMAIL: "email",
    DEBUG_MODE: "boolean",
  },
  options: {
    exitOnFail: true,
    logStyle: "color",
  },
};

new EnvGuard(config).validate();

Quick Start (JavaScript)

const { EnvGuard } = require("env-preflight");

const config = {
  required: {
    API_KEY: "string",
    PORT: "number",
    DATABASE_URL: "url",
    ADMIN_EMAIL: "email",
    DEBUG_MODE: "boolean",
  },
  options: {
    exitOnFail: true,
    logStyle: "color",
  },
};

new EnvGuard(config).validate();

Using with dotenv (optional)

import dotenv from "dotenv";
dotenv.config();

import { EnvGuard } from "env-preflight";
new EnvGuard({ required: { API_KEY: "string" } }).validate();

Env Preflight only reads process.env. Load envs however you prefer (dotenv, shell, CI vars, Docker, etc.).

Configuration

• required: map of env var names to rule strings
  • Allowed rules: 'string' | 'number' | 'boolean' | 'url' | 'email'
  • Note on enums: treat enums as strings in phase 1; enforce allowed values in your app logic
  • Important: use string literals for rules. Do not pass TypeScript types like string/number.
• options (optional):
  • exitOnFail (boolean): exit process with code 1 when invalid – default true
  • logStyle ("color" | "plain"): colorized or plain output – default color

Default options:

{
  exitOnFail: true,
  logStyle: 'color'
}

Runtime behavior

• validate() checks each required env var:
  • Missing → error collected
  • Present but wrong type → error collected
• If there are errors:
  • A friendly block is printed
  • If exitOnFail is true, the process exits with code 1
• Returns true when valid, false otherwise

Output examples

Color style (colors not rendered here):

[env-preflight] Oops… preflight checks failed

The following environment variables need attention:
- ✖ Missing required environment variable: "DATABASE_URL"
- ✖ Environment variable "PORT" must be a valid number.
- ✖ Environment variable "ADMIN_EMAIL" must be a valid email.

Action: Update your environment (.env, shell, CI) and restart the app.
Status: Not cleared for takeoff 🚫🚀

Plain style:

[env-preflight] Oops… preflight checks failed

The following environment variables need attention:
- ✖ Missing required environment variable: "DATABASE_URL"
- ✖ Environment variable "PORT" must be a valid number.
- ✖ Environment variable "ADMIN_EMAIL" must be a valid email.

Action: Update your environment (.env, shell, CI) and restart the app.
Status: Not cleared for takeoff 🚫🚀

Success message:

[env-preflight] ✅ Environment variables validated successfully, server is cleared for takeoff! 🚀

Best practices

• Load envs early (before creating your server/app)
• Keep secrets out of source control; use .env for local dev and CI secrets for pipelines
• Run Env Preflight in CI to catch misconfigurations before deploy

Compatibility

• Node.js: 14+ recommended
• Module format: CommonJS build
• Colors: Uses chalk@4 (CommonJS). If your app is pure ESM and you prefer chalk@5, migrate your project to ESM.

API Reference

class EnvGuard {
  constructor(config: EnvGuardConfig);
  validate(): boolean;
}

type ValidationRule = "string" | "number" | "boolean" | "url" | "email";

interface IOptions {
  exitOnFail: boolean;
  logStyle: "color" | "plain";
}

interface EnvGuardConfig {
  required: Record<string, ValidationRule>;
  options?: IOptions;
}

Troubleshooting

• “Why isn’t { PORT: number } working?”
  • Rules must be string literals (e.g., { PORT: 'number' }). TypeScript types do not exist at runtime.
• “What counts as a boolean?”
  • Accepted: "true" | "false" | "1" | "0" | "yes" | "no" (case-insensitive)
• “Do I need dotenv?”
  • No. EnvGuard only reads process.env. Use any loader or deployment env.

Contributing

Issues and PRs are welcome.

License

ISC © Igomigo Fatai Victor