✨ Introduction

Typenv introduces the .envx file format — a structured, schema-aware and type-safe evolution of traditional .env files. With support for conditional logic, rich metadata, multiline strings, and validation, it helps build robust configuration layers for modern applications.

Built with TypeScript and Node.js in mind, but designed to support other languages in future releases.

Why TypeEnv?

Traditional .env files are simple but limited:

• ❌ No type safety — all values are strings
• ❌ No validation — missing or malformed config leads to runtime errors
• ❌ No metadata — no built-in documentation or structure
• ❌ No logic — can’t dynamically derive values

TypeEnv solves all of these with a new .envx format:

• Type-safe config with schema enforcement
• Ternary logic & variable interpolation
• Built-in documentation (description, deprecated, etc.)
• Robust validation to prevent runtime errors

📦 Installation

npm install typenvx
# or
yarn add typenvx
# or
pnpm add typenvx

Usage Overview

Typenv provides multiple ways to work with environment configurations:

• CLI tools for generating .env, metadata and types
• Type-safe runtime loading APIs
• Support for multiple environments (e.g. .envx.dev, .envx.prod)
• Optional transformation to standard .env files while preserving type metadata

CLI Commands

| Command | Description | |----------------------|-----------------------------------------------------| | npx typenvx generate | Generates .env, envx.meta.json, and TS types | | npx typenvx build | Builds only .env from .envx | | npx typenvx types | Outputs TypeScript type definitions | | npx typenvx check | Validates .envx against schema definitions | | npx typenvx watch | Watches files and auto-builds on change |

You can configure CLI behavior with an optional envx.config.json:

{
  "input": "./.envx",
  "outputs": {
    "env": "./.env",
    "types": "./types/envx.ts",
    "metaFilePath": "."
  },
  "overwrite": true
}

Programmatic API

Typenv provides runtime APIs to work with environment data in a type-safe way:

import { getEnv, getEnvx, loadEnvx } from "typenvx";

// Uses .env + envx.meta.json (type-safe)
const env = getEnv();
if (env.DEV_MODE) {
  console.log("Development mode is enabled");
}

// Directly parses .envx at runtime
const envx = getEnvx();
console.log(envx.API_URL);

// Loads .envx into process.env (imperative style)
loadEnvx();
console.log(process.env.NODE_ENV);

Output Artifacts

When you run npx typenvx generate, the following files are created:

• .env — standard format for compatibility
• envx.meta.json — includes parsed schema info
• envx.ts — type definitions for TypeScript IDE support

📄 Example Syntax: .envx

DEV_MODE=${NODE_ENV} == "development" ? true : false
API_URL=${DEV_MODE} ? "http://localhost:3000#hash" : "https://api.example.com"
API_TOKEN=${DEV_MODE} ? "dev-token" : "prod-token"
FULL_API_URL="${API_URL}?token=${API_TOKEN}&env=${NODE_ENV}"
PORT=8080
MULTILINE_EXAMPLE="""
Hello!
I am .ENVX, the better .env format.
"""
GREETING="Hello \"user\"!"


[DEV_MODE]
type="boolean"

[PORT]
type="number"
required=true
description="Application port"

[NODE_ENV]
type="enum"
values=["development", "production", "test"]
default="development"
required=true

Multi-Environment Support

Typenv supports multiple environment variants using naming conventions like:

• .envx.local
• .envx.dev
• .envx.prod

Example:

npx typenvx build --input .envx.dev --output .env.dev --metaFilePath . --overwrite

📚 Documentation

Full docs & guides: https://typenv.trymagic.xyz/docs

Roadmap

• [x] Type-safe parsing and schema enforcement
• [x] CLI tooling
• [x] TypeScript type generation
• [x] VSCode syntax plugin
• [ ] Support for Python, Php & other languages
• [ ] Will be prioritized based on community feedback and evolving needs

🧩 VSCode Extension

Official VSCode extension for syntax highlighting and commands like "Generate .env" and "Generate Types".

→ Download from Marketplace

🤝 Contributing

Have an idea or found a bug?
Open an issue or submit a PR — we’d love to hear from you!

License

MIT © Trymagic

Created with ❤️ by @onurartan
Maintained by Trymagic Labs