v0.3.1

Environment variables you can trust at runtime

Validate, secure, and manage your environment variables with full TypeScript inference. From web apps to autonomous AI agents — your config is always correct, your secrets always protected. Built on Effect Schema.

Inspired by t3-env, powered by Effect Schema.

Get Started View on npm

$ bun add @ayronforge/better-env effect

env.ts

import { createEnv, redacted, url } from "@ayronforge/better-env"
import { Schema } from "effect"

export const env = createEnv({
  server: {
    OPENAI_API_KEY: redacted(Schema.String),
    DATABASE_URL: Schema.String,
    VECTOR_STORE_URL: url,
  },
  client: {
    NEXT_PUBLIC_APP_URL: url,
  },
  shared: {
    NODE_ENV: Schema.Literal(
      "development", "production", "test"
    ),
  },
})

Everything you need

A complete toolkit for environment variable management, from schema validation to cloud secret resolution. Whether you're building a web app or an autonomous agent.

Powered by Effect Schema

Use the full power of Effect Schema for validation, transformation, and branding. Every env var gets runtime type checking with structured, parseable error messages.

Full Type Inference

Automatic TypeScript inference from your schema definitions. No manual type annotations needed — your env object is fully typed.

Client/Server Separation

Define server-only and client-safe variables separately. Accessing server vars on the client throws at runtime — no secrets leaked, even in agent-generated output.

Framework Presets

Pre-configured setups for Next.js, Vite, Expo, and more. Get the right prefix rules and runtime env settings out of the box.

Secret Manager Integrations

Resolve env vars from AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, or 1Password. Pull secrets from wherever your agents are deployed.

Composable & Extensible

Compose multiple env configs with `extends`. Build shared base configs and layer service-specific vars on top — ideal for multi-agent architectures.

Built for Autonomous Systems

AI agents run without supervision. Their environment config can't be wrong.

Fail Before You Run

Validation runs at startup, not at first use. Missing or malformed secrets crash immediately with a structured error — not halfway through a task.

Secrets That Stay Secret

redacted wraps sensitive values so they never appear in logs, traces, or agent output. Your API keys stay invisible even when agents serialize their state.

Errors Agents Can Act On

Every validation failure returns a typed, structured error with the exact variable name and reason. Agents can read what went wrong and correct course — no log parsing required.

Modular Design

Compose, layer, and override configs across services and environments. Base credentials, tool-specific keys, and deployment overrides — all validated, all typed, all composable.

Integrations

Resolve environment variables directly from your cloud provider's secret manager. No .env files in production.

AWS Secrets Manager

import { fromAwsSecrets } from "@ayronforge/better-env/aws"

fromAwsSecrets({
  secrets: {
    DB_PASS: "prod/db-password",
    DB_USER: "prod/db-credentials#username",
  },
  region: "us-east-1",
})

Azure Key Vault

import { fromAzureKeyVault } from "@ayronforge/better-env/azure"

fromAzureKeyVault({
  secrets: {
    DB_PASS: "db-password",
    API_KEY: "my-api-key",
  },
  vaultUrl: "https://my-vault.vault.azure.net",
})

GCP Secret Manager

import { fromGcpSecrets } from "@ayronforge/better-env/gcp"

fromGcpSecrets({
  secrets: {
    DB_PASS: "db-password",
    API_KEY: "projects/my-project/secrets/api-key/versions/2",
  },
  projectId: "my-project",
})

1Password

import { fromOnePassword } from "@ayronforge/better-env/1password"

fromOnePassword({
  secrets: {
    DB_PASS: "op://vault/item/field",
    API_KEY: "op://vault/another-item/credential",
  },
})

Framework Presets

Get started instantly with pre-configured presets for popular frameworks.

Next.js

NEXT_PUBLIC_

import { createEnv, postgresUrl, url } from "@ayronforge/better-env"
import { nextjs } from "@ayronforge/better-env/presets"

const env = createEnv({
  ...nextjs,
  server: { DATABASE_URL: postgresUrl },
  client: { API_URL: url },
})

Vite

VITE_

import { createEnv, requiredString, url } from "@ayronforge/better-env"
import { vite } from "@ayronforge/better-env/presets"

const env = createEnv({
  ...vite,
  server: { SECRET_KEY: requiredString },
  client: { API_URL: url },
})

Expo

EXPO_PUBLIC_

import { createEnv, url } from "@ayronforge/better-env"
import { expo } from "@ayronforge/better-env/presets"

const env = createEnv({
  ...expo,
  client: { API_URL: url },
})