@geenius/env

Type-safe environment variable validation and access for Geenius packages. @geenius/env is a framework-agnostic utility package backed by Zod schemas and structured Geenius errors.

Install

pnpm add @geenius/env zod

zod is a peer dependency. Source packages in this repository keep local Geenius package dependencies as link: references until publish-day range refresh.

Usage

import { createEnvValidator, validateEnv } from '@geenius/env'
import { z } from 'zod/v4'

const env = validateEnv({
  API_URL: z.string().url(),
  PORT: z.coerce.number().int().positive().default(3000),
})

const validateServerEnv = createEnvValidator(
  {
    API_KEY: z.string().min(1),
    RETRIES: z.coerce.number().int().default(3),
  },
  { throw: true }
)

const serverEnv = validateServerEnv({
  env: {
    API_KEY: 'local-secret',
  },
})

Runtime env sources are selected in this order: Vite or browser import.meta.env, Node process.env, Deno Deno.env.toObject(), then an empty object. Every API also accepts an explicit env source for tests and adapters.

API Reference

| Export | Purpose | | --- | --- | | env(schema, config?) | Strict validation wrapper that throws on invalid or missing values. | | optionalEnv(schema, config?) | Non-throwing validation that returns only valid values. | | validateEnv(schema, config?) | Validates an env source with Zod and returns typed output. | | createEnvValidator(schema, config?) | Builds a reusable validator with a cached schema snapshot. | | loadEnv(path, options?) | Loads dotenv files with quote, escape, comment, and export support. | | getEnv(key, ...) | Reads one value with optional default and Zod validation overloads. | | hasEnv(key, options?) | Checks value presence, with configurable empty-string handling. | | requireEnv(keyOrKeys, options?) | Returns one required value or asserts that a list exists. | | getEnvs(keys, options?) | Reads a typed record for multiple keys. | | parseEnvJson(key, default?, options?) | Parses JSON-encoded values. | | parseEnvBool(key, default?, options?) | Parses true and false token sets. | | parseEnvNumber(key, default?, options?) | Parses finite numbers with optional min and max bounds. | | parseEnvList(key, default?, options?) | Parses separated string lists. | | EnvironmentValidationError | Validation failure with Zod issue context. | | MissingEnvironmentVariableError | Required key failure with missing key context. | | InvalidEnvironmentVariableError | Single-key parse or validation failure. |

Variants

@geenius/env has one framework-agnostic implementation under packages/env. It has no UI variants, DB variants, Storybook apps, visual tests, or accessibility stories.

Testing

pnpm type-check
pnpm test
pnpm test:contracts
pnpm lint

pnpm test builds the package, runs the env-core unit tests, and runs root contract tests for the exports map, emitted declarations, and packed tarball consumer smoke.

Documentation

The public authority doc is .docs/DOCS/PACKAGES/ENV.md. Requirements and shipped scope are tracked in .docs/PRDS/packages/PACKAGE_ENV_PRD.md, .docs/PLANS/packages/env/PLAN.md, and .docs/FEATURES/packages/env/FEATURES.md.

License

FSL-1.1-Apache-2.0. See LICENSE.