convar-strict

Automatic .env.example validation for convar. Uses your existing .env.example file to validate required environment variables at runtime.

Overview

Most projects maintain a .env.example file to document required environment variables. convar-strict leverages this file to automatically validate your environment, eliminating the need to manually specify required fields or maintain a separate schema.

Key features:

• ✅ Uses .env.example as the source of truth for required variables
• ✅ Validates on first use with clear error messages
• ✅ Warns about undocumented variables in .env
• ✅ Drop-in replacement for convar
• ✅ Zero configuration required
• ✅ Full TypeScript support

Installation

npm install convar-strict
# or
yarn add convar-strict

Usage

Basic Example

.env.example:

DATABASE_URL=
API_KEY=
PORT=3000

# Optional - commented variables are not required
# DEBUG=false

app.js:

const convar = require("convar-strict");

const config = {
  database: convar("DATABASE_URL"),
  apiKey: convar("API_KEY"),
  port: convar("PORT"),
  debug: convar("DEBUG"), // Optional - won't throw if missing
};

If required variables are missing, you'll get a clear error on first use:

Error: Missing required environment variables from .env.example: DATABASE_URL, API_KEY
Please ensure these variables are set in your .env file or environment.

Variables in .env but not in .env.example trigger a warning:

⚠️  Warning: The following environment variables are not in .env.example:
  SECRET_TOKEN
  Consider adding them to .env.example to document them for your team.

Configuration

The package maintains full compatibility with convar. Optional configuration for advanced use cases:

const convar = require("convar-strict");

convar.configure({
  examplePath: ".env.example", // Path to .env.example file
  warnOnExtra: true, // Warn about undocumented variables
  throwOnMissing: true, // Throw error on missing required variables
});

Comparison

| Feature | convar | convar-strict | | -------------------------- | --------- | ------------- | | Load env variables | ✅ | ✅ | | Validate required fields | ❌ Manual | ✅ Automatic | | Uses existing .env.example | ❌ | ✅ | | Warns on undocumented vars | ❌ | ✅ | | No schema duplication | ❌ | ✅ | | Drop-in replacement | N/A | ✅ |

vs. other validation libraries:

Libraries like envalid, t3-env, and @xho/env-validator require defining a schema in code. convar-strict uses the .env.example file you already maintain, eliminating duplication.

License

MIT