Venvy

Strict environment variable governance for modern applications

---

Venvy is a professional command-line tool and library designed for strict environment variable governance in Node.js, React, Next.js, and React Native applications. It ensures that your applications always run with a valid, type-safe, and complete set of environment variables.

Why Venvy?

Stop letting environment variables cause runtime errors and configuration nightmares. Venvy brings enterprise-grade environment governance to your projects with zero configuration overhead.

Core Purpose

• Strict Validation: Enforce that all required environment variables are present and match defined types at application startup or during CI/CD
• Type Safety: Automatically infer TypeScript types from your environment schema, ensuring that process.env access is safe and predictable
• Cross-Environment Consistency: Detect missing or extra variables across different environment files (e.g., .env.development vs. .env.production)
• Simplified Onboarding: Generate .env.example files automatically to help new developers set up their local environments quickly
• CI/CD Integration: Exit with non-zero codes when validation fails, allowing you to catch configuration errors before they reach production

Features

• Schema-Based Definition: Define your environment structure using a fluent API that supports strings, numbers, booleans, enums, and URLs
• Advanced Validators: Built-in support for email(), ip(), port(), and custom regex() validation
• Conditional Validation: Use requiredIf() to make variables required only under specific conditions
• Automatic Documentation: Generate and inject environment variable tables directly into your README.md
• Git Hooks: Automatically set up pre-commit hooks to prevent invalid configurations from being committed
• JIT Schema Loading: Load .ts schema files directly in the CLI without a manual compilation step
• Project Scaffolding: Use init to automatically generate a schema from your existing .env files
• Interactive Sync: Use sync to interactively fill in missing variables in your .env
• Zod Integration: Power Venvy with your existing Zod schemas using the fromZod bridge

Installation

npm install venvy

Quick Start

1. Define Your Schema

Create a file named venvy.schema.ts (or venvy.schema.js) in your project root:

import { string, number, enumeration, url, email, port } from "venvy";

export const env = {
  DB_URL: url().required().description("Main database connection string"),
  PORT: port().default(3000).description("Application server port"),
  NODE_ENV: enumeration(["development", "production", "test"]).required(),
  ADMIN_EMAIL: email().requiredIf((vars) => vars.NODE_ENV === "production"),
  JWT_SECRET: string().required().minLength(32),
  API_RATE_LIMIT: number().default(1000).min(1).max(10000),
  CORS_ORIGINS: string().default("http://localhost:3000").regex(/^https?:\/\/.+/),
};

Using Zod

If you already use Zod, you can bridge your schema seamlessly:

import { z } from "zod";
import { fromZod, defineEnv } from "venvy";

const zodSchema = z.object({
  PORT: z.number().default(3000).describe("App server port"),
  DB_URL: z.string().url().describe("Main DB URL"),
  NODE_ENV: z.enum(["development", "production", "test"]),
});

export const env = defineEnv(fromZod(zodSchema));

2. CLI Commands

Venvy provides a powerful CLI for management and automation.

Initialize Venvy in an existing project:

npx venvy init

Interactively sync missing variables:

npx venvy sync

Validate the current environment:

npx venvy validate

Compare environments:

npx venvy diff development production

Inject documentation table into README:

npx venvy docs

Generate .env.example:

npx venvy generate

Set up Git pre-commit hook:

npx venvy hook

3. Runtime Protection

To protect your application at runtime, call defineEnv at the very beginning of your entry point:

import { defineEnv } from "venvy";
import { env as schema } from "./venvy.schema.js";

// This validates the environment and returns a type-safe object
export const env = defineEnv(schema);

console.log(env.DB_URL); // Fully typed as string
console.log(env.PORT);    // Fully typed as number

Advanced Usage

Conditional Requirements

Make variables required only in specific scenarios:

export const env = {
  NODE_ENV: enumeration(["development", "production", "test"]).required(),
  DEBUG_MODE: boolean().default(false),
  SENTRY_DSN: url().requiredIf((vars) => vars.NODE_ENV === "production"),
  LOG_LEVEL: enumeration(["error", "warn", "info", "debug"])
    .default("info")
    .requiredIf((vars) => vars.DEBUG_MODE),
};

Custom Validation

Add your own validation logic:

export const env = {
  API_KEY: string()
    .required()
    .regex(/^sk_[a-zA-Z0-9]{32}$/)
    .description("Stripe API key (starts with sk_)"),
  
  DATABASE_POOL_SIZE: number()
    .default(10)
    .min(1)
    .max(100)
    .description("Database connection pool size"),
};

Environment Comparison

Ensure consistency across your environments:

# Check what's different between staging and production
npx venvy diff staging production

# Output:
# Missing in production: DEBUG_MODE
# Different values: API_RATE_LIMIT (staging: 100, production: 1000)
# All other variables match!

Technical Architecture

Venvy is designed to be lightweight with minimal dependencies. It leverages TypeScript's advanced type inference to provide a seamless developer experience without requiring manual type maintenance or complex code generation.

Key Design Principles

• Zero Runtime Overhead: Validation happens once at startup
• Type Safety First: All environment access is fully typed
• Developer Experience: Intuitive CLI with helpful error messages
• CI/CD Ready: Built for automated workflows

API Reference

Core Validators

Validator	Description	Example
string()	String values	string().required().minLength(5)
number()	Numeric values	number().default(42).min(0).max(100)
boolean()	Boolean values	boolean().default(false)
url()	URL validation	url().required().protocol("https")
email()	Email validation	email().required()
port()	Port numbers	port().default(3000)
enumeration()	Enum values	enumeration(["dev", "prod"]).required()

Advanced Methods

• .required() - Mark as required
• .default(value) - Set default value
• .description(text) - Add description for docs
• .requiredIf(condition) - Conditional requirement
• .regex(pattern) - Custom regex validation
• .min/max - Numeric/string constraints

Community & Support

• Full Documentation - Comprehensive guides and API reference
• Issue Tracker - Report bugs and request features
• Discussions - Community discussions and Q&A

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/ElnatanSamuel/venvy.git
cd venvy
npm install
npm run dev

License

MIT © Elnatan Samuel

---

Star this repo if Venvy helped you!

Made with ❤️ by Elnatan Samuel

Environment Variables

Variable	Type	Required	Default	Description
DB_URL	url	Yes	-	Main PostgreSQL connection string
PORT	port	No	3000	Application server port
NODE_ENV	enum	Yes	-	-
ADMIN_EMAIL	email	Conditional	-	System administrator email for alerts
JWT_SECRET	string	Yes	-	Secret key for signing JSON Web Tokens