Env Reader — the AtomForge character at work

@atom-forge/env-reader · Configuration

Fail at startup, not in production.

Env Reader turns string-based environment variables into explicitly typed application values. Each field chooses its own parser and default, so missing or invalid configuration stops the application before it accepts work.

TypeScript Environment variables Validation Configuration

What it is

One configuration boundary.

Call the reader’s methods while building startup configuration: string, int, float, boolean, oneOf, url, regex and list, plus file and dir for paths resolved against the project root. A missing variable without a default throws immediately.

The package does not infer a schema from an environment file and does not load .env files for you; loading belongs to your runtime or deployment.

Why choose Env Reader?

Explicit parsers

Every value says what it is and what its default is. The configuration object is something you can read and review.

Typed, read-only view

asReadonly gives a DeepReadonly TypeScript view at zero runtime cost. It does not freeze the object.

Paths with a safety rail

file and dir resolve against the project root and, by default, refuse to leave it.

How it works

  1. Create the reader

    Pass an absolute project-root path to EnvReader.

  2. Describe each value

    Choose a parser and, only where it is a policy decision, a default.

  3. Inject the result

    Pass the configuration into services instead of reading process.env across business code.

An honest fit check

Trade-offs, not fine print

You maintain the schema

The configuration object, parsing choices and defaults are written by hand.

Not a secrets manager

Never serialize server secrets into browser-visible state, and do not silently default a required production secret.

In practice

Parse configuration once

Pass an absolute application project-root path; environment loading is application-owned.

TypeScript · Illustrative · adapted from the source texts; package API not verified here
import { EnvReader, asReadonly } from '@atom-forge/env-reader';

export function readConfig(projectRoot: string) {
  const env = new EnvReader(projectRoot);
  return asReadonly({
    app: { environment: env.oneOf('APP_ENV', ['dev', 'prod', 'test'], 'prod') },
    database: {
      connectionString: env.string('DATABASE_URL'),
      maxPool: env.int('DB_POOL_MAX', 20),
    },
    auth: { secret: env.string('JWT_SECRET') },
  });
}