Installation & Quick Start

Typenvx is a modern, zero-dependency environment variable parser and validator designed to help you manage .envx files easily and safely. It provides a CLI and runtime utilities for validating, generating, and accessing environment variables with strong TypeScript support.

Why Typenvx?

Parse and validate your environment files before runtime
Generate TypeScript types for safe access
Support complex features like string interpolation and conditional values
Prevent bugs caused by missing or mistyped environment variables

Step 1: Install Typenvx

npm install typenvx

pnpm add typenvx

yarn add typenvx

Step 2: Create a `.envx` File

Create a file named .envx in your project root with environment variables:

# Set environment mode
NODE_ENV = "development"

# Define API URL based on NODE_ENV using ternary interpolation
API_URL = ${NODE_ENV} == "production" ? "https://api.example.com" : "http://localhost:3000"

# Variable with schema validation
[API_URL]
type = "url"
required = true

Explanation:

NODE_ENV is set explicitly.
API_URL uses ternary interpolation to switch URLs based on NODE_ENV.
Schema section [API_URL] enforces that the URL is valid and required.

Step 3: Generate Env Files and Types

Run the CLI command to process your .envx file:

npx typenv generate

This command does:

Parses and validates .envx
Creates a .env file with resolved values
Generates TypeScript typings (envx.ts) for safe runtime access
Outputs envx.meta.json with schema info for runtime checks

Step 4: Use Typenvx in Your Code

Access with Strong Typing

import { getEnvx } from "typenvx";
import type { EnvVars } from "./types/envx";

const env = getEnvx<EnvVars>();

console.log("API URL:", env.API_URL); // Typed, validated access

What does getEnvx do?

Reads environment variables at runtime
Validates them against the generated schema
Returns a fully typed object with all your environment variables

import { getEnv } from "typenvx";
import type { EnvVars } from "./types/envx";

const env = getEnv<EnvVars>();

console.log("API URL:", env.API_URL); // Typed, validated access

What does getEnv do?

Loads environment variables from the generated .env file
Validates variables using the schema defined in envx.meta.json.
Returns a fully typed object with your environment variables (EnvVars).
Throws errors if validation fails, ensuring safe and consistent runtime configuration.

Inject into `process.env` (Optional)

If you want to populate process.env safely:

import { loadEnvx } from "typenvx";

loadEnvx(); // Validates and injects variables into process.env

console.log("NODE_ENV from process.env:", process.env.NODE_ENV);

Step 5: Validate Without Generating

Quickly validate your .envx file without generating outputs:

npx typenv validate

This helps catch errors early, for example in CI pipelines.

Step 6: Watch Mode for Development

Automatically re-generate .env and typings on changes:

npx typenv watch

This improves developer experience by keeping environment files always up to date.

Learn about:

String Interpolation — How to reuse variables inside .envx
Ternary Conditions — Dynamic config per environment
Schema Reference — Full details on supported keys like type, default, required

Quick Start