https://github.com/srmlcn/env-ready
A schema-driven environment variable loader for Node.js projects
https://github.com/srmlcn/env-ready
adapter config dotenv env environment fail-fast joi loader nodejs runtime safe schema typescript validation variables zod
Last synced: 3 months ago
JSON representation
A schema-driven environment variable loader for Node.js projects
- Host: GitHub
- URL: https://github.com/srmlcn/env-ready
- Owner: srmlcn
- License: mit
- Created: 2025-07-03T16:03:33.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-04T18:35:59.000Z (11 months ago)
- Last Synced: 2025-10-09T23:56:32.480Z (8 months ago)
- Topics: adapter, config, dotenv, env, environment, fail-fast, joi, loader, nodejs, runtime, safe, schema, typescript, validation, variables, zod
- Language: TypeScript
- Homepage:
- Size: 157 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# env-ready
[](https://github.com/srmlcn/env-ready/actions/workflows/test.yml) [](https://codecov.io/github/srmlcn/env-ready) [](https://www.npmjs.com/package/env-ready) [](https://github.com/semantic-release/semantic-release)
**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
```bash
npm install env-ready
```
## Usage
### Basic Example
Create a schema using your preferred validation library, for instance, in `src/env.ts`:
```typescript
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:
```typescript
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
```javascript
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
```typescript
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(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:
```typescript
import { loadEnv } from "env-ready"
// Define a custom schema class
class CustomSchema {
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()
// Load and validate environment variables using your custom schema
export const env = loadEnv(mySchema)
```
## Validator Compatibility
- [Zod](https://github.com/colinhacks/zod)
- [Joi](https://github.com/hapijs/joi)
- Custom schemas
- Must implement: `parse(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!