Introduction

Type-safe environment variables powered by Effect Schema. Validate, transform, and manage env vars with full TypeScript inference.

@ayronforge/envil is a type-safe environment variable library built on Effect Schema. It validates your env vars at startup, gives you full TypeScript inference, and prevents client-side access to server secrets.

Why envil?

Environment variables are stringly-typed by default. A missing DATABASE_URL or a malformed PORT shouldn’t crash your app deep in a request handler — it should fail immediately at startup with a clear error message.

envil gives you:

• Runtime validation — every env var is parsed through Effect Schema at startup
• Full type inference — your env object is fully typed from your schema definitions, no manual annotations needed
• Client/server separation — define server, client, and shared buckets; accessing a server variable on the client throws at runtime
• Framework presets — pre-configured prefix rules for Next.js, Vite, and Expo
• Cloud secret resolution — pull env vars from AWS Secrets Manager, GCP, Azure Key Vault, or 1Password
• Composable configs — split env definitions across modules and merge them with extends

Quick example

import { createEnv, port, requiredString, boolean } from "@ayronforge/envil"
import { Schema } from "effect"

export const env = createEnv({
  server: {
    DATABASE_URL: requiredString,
    PORT: port,
    DEBUG: boolean,
  },
  client: {
    NEXT_PUBLIC_API_URL: requiredString,
  },
  shared: {
    NODE_ENV: Schema.Literal("development", "production", "test"),
  },
})

// Fully typed: env.DATABASE_URL is string, env.PORT is number
console.log(env.DATABASE_URL)

If any variable is missing or invalid, you get a clear error at startup:

EnvValidationError: Invalid environment variables:
DATABASE_URL: Expected a string with a length of at least 1, but got undefined
PORT: Expected Port (1-65535), but got "not-a-number"

Acknowledgements

This project is heavily inspired by T3 Env by T3 OSS. Thanks to the T3 team for their work and contributions to open source.