typed-env-handler

typed-env-handler is a TypeScript/JavaScript package for simple, secure, and type-safe handling of environment variables. It helps load, validate, and access environment variables in your code with static typing. Starting with version 0.3.0, Docker secrets are also supported.

Why I Built This

Traditional tools like dotenv load environment variables into process.env purely as raw, untyped strings—without verifying whether required variables exist or if data types match. Missing configuration or subtle type conversion bugs (such as "false" evaluating as a truthy boolean) often go unnoticed until runtime in production.

typed-env-handler was created to solve these issues:

• Fail Fast: Immediately validates all required environment variables at application startup. If any variable is missing or malformed, the process exits early with an informative error message.
• True Type Safety in TypeScript: Variables are parsed at runtime and provided with static typing in your code—a boolean is a real boolean, a number is a number, and not a raw string.
• Seamless Docker Deployment: Supports Docker secrets (/run/secrets/*) transparently alongside standard environment variables and automatically masks sensitive secrets in debug logs.

Features

• Typed Environment Variables: Define and consume environment variables with static typing, including static helper functions for minimal boilerplate.
• Validation: Ensure all required variables are present and correctly formatted with clear, actionable error messages.
• Docker Secrets & Masking: Declare variables as secrets (loaded from .env or from Docker at /run/secrets/<name>). Secrets are automatically masked as *** in debug logs.
• Easy Integration: Seamlessly integrates into existing Node.js and TypeScript projects.
• Error Handling: Provides precise error messages for missing or invalid configuration values.

Use Cases

Ideal for any Node.js application where configuration must be validated and strongly typed, such as API keys, database credentials, or feature flags. Especially well suited for secure containerized production deployments with Docker.

Example

import { HandleEnv } from "@christian-wechsel/typed-env-handler";

const envHandler = new HandleEnv({
  PORT: HandleEnv.number(),
  NODE_ENV: HandleEnv.string(),
  API_KEY: HandleEnv.string({ 
    secret: { dockerName: "api_key" } // Loaded from /run/secrets/api_key in Docker
  }),
  THIRD_PARTY_SECRET: HandleEnv.string({
    secret: true // Loaded from environment, masked as *** in debug logs
  }),
  DEBUG: HandleEnv.boolean({ defaultValue: false }),
});

const PORT = envHandler.getValue("PORT"); // typed as number
const NODE_ENV = envHandler.getValue("NODE_ENV"); // typed as string
const API_KEY = envHandler.getValue("API_KEY"); // typed as string, loaded from Docker secret
const THIRD_PARTY_SECRET = envHandler.getValue("THIRD_PARTY_SECRET"); // typed as string
const DEBUG = envHandler.getValue("DEBUG"); // typed as boolean

Constructor Options

The second parameter of the constructor is optional and accepts the following settings:

| Option | Type | Default | Description | | --- | --- | --- | --- | | docker.pathSecrets | string | /run/secrets/ | Path where Docker secrets are mounted | | debugLogs | boolean | false | Enables verbose debug logging |

const envHandler = new HandleEnv(
  {
    API_KEY: HandleEnv.string({
      secret: { dockerName: "api_key" },
    }),
  },
  {
    docker: { pathSecrets: "/custom/secrets/path/" },
    debugLogs: true, // Only enable during development
  },
);

Security Note: Debug logs output variable names, paths, and values. To prevent leaks, HandleEnv masks any value flagged with secret (secret: true or secret: { dockerName: "..." }) as ***.

In addition, when NODE_ENV=production, debug logs are always automatically suppressed, regardless of the configuration setting.

Docker Integration

When running inside a Docker container, no .env file is loaded. Instead, all values are read directly from process environment variables (e.g. defined via environment: in Docker Compose). Variables declared as secrets are loaded from the configured secret mount path.

Prerequisites

Set IS_DOCKER=true in your Docker environment. This instructs HandleEnv to skip loading any .env file.

Example docker-compose.yaml

name: my-app
services:
  server:
    image: my-app-image:latest
    environment:
      - NODE_ENV=production
      - IS_DOCKER=true   # Prevents loading a .env file
      - PORT=3000
      - DEBUG=false
    secrets:
      - api_key          # Mounted at /run/secrets/api_key

secrets:
  api_key:
    file: ./secrets/api_key.txt

Example Docker Build Mount

RUN --mount=type=secret,id=api_key,target=/run/secrets/api_key ...

Inside your application, HandleEnv automatically detects the container environment and loads secrets directly from the mounted files.