env-ready

env-ready provides a centralized, fail-fast mechanism for validating environment variables at startup—designed to reduce misconfiguration, improve safety, and support your preferred schema validation library through validator inference.

Why env-ready?

• Type-safe by design: Built with TypeScript for first-class static validation
• Fail-fast startup: Surface configuration errors early, not during execution
• Schema-agnostic architecture: Bring your own validator (zod, joi, etc.)
• Minimal runtime footprint: Focused, purpose-built utility with no bloat

Goals

• Centralize environment variable validation and access
• Fail fast on missing or malformed variables
• Enable schema flexibility through validator inference
• Keep the runtime overhead minimal and the API ergonomic

Installation

npm install env-ready

Usage

Basic Example

Create a schema using your preferred validation library, for instance, in src/env.ts:

import { loadEnv } from "env-ready"
import { z } from "zod"

// Define your schema using Zod
const schema = z.object({
  FOO: z.string().min(1, "FOO is required"),
  BAR: z.number().optional(),
})

// Load and validate environment variables
export const env = loadEnv(schema)

Then, in your application code:

import { env } from "./env"

console.log(env.FOO) // Access validated environment variable
console.log(env.BAR) // Optional variable, may be undefined

Joi Schemas

Joi schemas are fully supported, but type inference is not available by default. To coerce Joi schemas into TypeScript types, you can use the joi-to-typescript package or manually define types that match your Joi schema.

JavaScript Example

const { loadEnv } = require("env-ready")
const Joi = require("joi")

// Define your Joi schema
const schema = Joi.object({
  FOO: Joi.string().required(),
  BAR: Joi.number(), // Optional by default
})

// Load and validate environment variables
const env = loadEnv(schema) // `env` will be typed as `any`
console.log(env.FOO) // Access validated environment variable
console.log(env.BAR) // Optional variable, may be undefined

TypeScript Example

import { loadEnv } from "env-ready"
import Joi from "joi"

// Define your Joi schema
const schema = Joi.object({
  FOO: Joi.string().required(),
  BAR: Joi.number(), // Optional by default
})

// Define TypeScript types based on your Joi schema
type EnvConfig = {
  FOO: string
  BAR?: number // Optional variable
}

// Load and validate environment variables
const env = loadEnv<EnvConfig>(schema) // `env` will be typed as `EnvConfig`
console.log(env.FOO) // Access validated environment variable
console.log(env.BAR) // Optional variable, may be undefined

Custom Schemas

You can also create custom schemas that implement the parse method:

import { loadEnv } from "env-ready"

// Define a custom schema class
class CustomSchema<T> {
  parse(env: unknown): T {
    // Custom parsing logic here
    return env as T
  }
}

// Define your custom schema type
type MyConfig = { FOO: string; BAR?: number }

// Create an instance of your custom schema
export const mySchema = new CustomSchema<MyConfig>()

// Load and validate environment variables using your custom schema
export const env = loadEnv(mySchema)

Validator Compatibility

• Zod
• Joi
• Custom schemas
  • Must implement: parse<T>(env: unknown): T

Contribute

If you find this project useful, consider:

• Starring the repository to improve visibility
• Using it in your projects and sharing feedback
• Opening issues for bugs, ideas, or validator support requests

Early adoption helps refine the direction and expand validator support. Thanks for your support!