typenvx/README.md

Typenv is a modern, type-safe alternative to .env files, providing advanced validation, intelligent interpolation, and conditional logic for better environment management.

![TypeEnv Banner](https://github.com/trymagiclabs/typenv/blob/main/assets/typenv-banner-light.png)

<p align="center">
<b>TypeEnv</b> is a type-safe alternative to .env files. It adds validation, conditional logic, and variable interpolation all through a structured format: <code>.envx</code>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/typenvx">
    <img src="https://img.shields.io/npm/v/typenvx?style=flat-square" />
  </a>
  <a href="https://github.com/trymagiclabs/typenv/actions">
    <img src="https://img.shields.io/github/actions/workflow/status/trymagiclabs/typenv/ci.yml?branch=main&style=flat-square" />
  </a>
  <a href="https://github.com/trymagiclabs/typenv/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/trymagiclabs/typenv?style=flat-square" />
  </a>
</p>

---


## ✨ 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

```bash
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`:

```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:

```ts
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

```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:

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

---


## 📚 Documentation

Full docs & guides: [https://typenv.trymagic.xyz/docs](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](https://marketplace.visualstudio.com/items?itemName=Trymagic.typenv)

---


## 🤝 Contributing

Have an idea or found a bug?  
Open an [issue](https://github.com/trymagiclabs/typenv/issues) or submit a PR — we’d love to hear from you!

---



## License

MIT © Trymagic


Created with ❤️ by [@onurartan](https://github.com/onurartan)  
Maintained by [Trymagic Labs](https://github.com/trymagiclabs)