@t3-oss/env-core

@t3-oss/env-core is the framework-agnostic core of t3-env, a tiny library that makes environment variables typesafe. You declare your server, client, and shared variables with a schema, and it validates them at startup so an app never boots with missing or malformed configuration. Access is fully typed and autocompleted, and a runtime Proxy prevents server-only secrets from ever being read on the client.

Rather than bundling a specific validator, it accepts any Standard Schema compliant library, so you can bring Zod, Valibot, or ArkType. It ships preset helpers for common platforms (Vercel, Netlify, Railway, Fly, Render, Supabase, Upstash, and more) and framework wrappers like @t3-oss/env-nextjs and @t3-oss/env-nuxt build on top of this core.

What You Get

• A createEnv function that validates process.env (or any runtime env) against your schema at boot
• Full TypeScript inference and autocompletion for every declared variable, including transforms and defaults
• Client/server access separation with a runtime Proxy that blocks server secrets on the client
• Validator freedom via the Standard Schema spec, so Zod, Valibot, or ArkType all work interchangeably
• Built-in presets for platforms like Vercel, Netlify, Railway, Fly, Render, Supabase, and Upstash

Common Use Cases

• Failing a deploy fast when a required environment variable is missing or malformed
• Sharing one typed env object across a codebase instead of scattering raw process.env reads
• Preventing accidental exposure of server-only secrets in client bundles
• Reusing platform-provided variables (VERCEL_URL, RAILWAY_*, etc.) through ready-made presets

Under The Hood

Architecture — The public surface is a single generic function, createEnv, in packages/core/src/index.ts. It resolves the runtime source (runtimeEnvStrict, runtimeEnv, or process.env), optionally coerces empty strings to undefined, then decides isServer via typeof window. It assembles a combined shape from _server, _shared, and _client and validates it either through a user-supplied createFinalSchema or the built-in parseWithDictionary in standard.ts, which walks each key and aggregates issues with prefixed paths. The validated value is merged with any extends presets and wrapped in a Proxy whose get trap enforces client/server access rules and ignores internal props like __esModule.

Tech Stack — Pure TypeScript, ESM-only, with zero runtime dependencies. Validators (zod, valibot, arktype) and typescript are optional peer dependencies, so nothing is pulled in unless used. The build uses tsdown with platform-neutral, unbundled output and generated .d.ts files. The repo is a Bun-managed monorepo with core, nextjs, and nuxt packages, plus a docs site and examples.

Code Quality — The core abstraction is the vendor-neutral Standard Schema interface defined in standard.ts, keeping the library decoupled from any single validator. Types are dense but purposeful (UndefinedOptional, Reduce, StrictOptions) to power inference and prefix enforcement. Validation is explicitly synchronous, guarded by ensureSynchronous which throws on Promises. Smoke test suites exist for Zod 3, Zod 4, Valibot, and ArkType, covering the primary code paths across supported validators.

API Design — createEnv is a single, well-documented entry point with heavily commented options (isServer, shared, extends, onValidationError, onInvalidAccess, skipValidation, emptyStringAsUndefined). Naming is consistent and the option names read declaratively. Getting started requires only a schema and a runtimeEnv mapping, and the extends/preset pattern keeps platform boilerplate out of user code.