TypeEnv is a type-safe alternative to .env files. It adds validation, conditional logic, and variable interpolation all through a structured format: .envx
---
## ✨ 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)