Dotenvx is a modern and type-safe alternative to traditional .env files. It brings validation, type inference, schema support, and a minimal CLI — all in a single developer-friendly solution.
Traditional .env files lack structure and safety:
- ❌ No type validation (everything is a string)
- ❌ No way to define required or optional values
- ❌ No default values or enums
- ❌ No documentation inside
.envitself
dotenvx solves this by allowing both configuration and schema to live in the same file (.envx), with first-class support for validation, multiline values, conditional logic, and more.
- ✅ Schema support with types, defaults, and requirements
- ✅ Validation on load, with meaningful errors
- ✅ Smart variable interpolation & ternary expressions
- ✅ Triple-quoted multiline values
- ✅ Built-in CLI (
dotenvx) for automation and CI/CD use - ✅ Type-safe runtime access via
getEnvx() - ✅ Compatible with
process.envusage
pnpm add dotenvxjs
# or
npm install dotenvxjsimport { loadEnvx, getEnvx } from "dotenvxjs";
// Loads and validates the .envx file (default is "./.envx")
loadEnvx();
const env = getEnvx();
console.log(env.PORT); // typed access, number
console.log(env.API_URL); // resolved with ternary + interpolation
console.log(env.NODE_ENV); // enum valueOnce loaded, all validated values are also available in process.env.
DEV_MODE=false
API_URL=${DEV_MODE} ? "http://localhost:3000" : "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
DATABASE_NAME="my_db"
WELCOME_TEXT="""
Welcome to the new config system.
This supports multi-line values easily.
"""
# schema definition starts here
[DEV_MODE]
type="boolean"
[PORT]
type="number"
required=true
[API_URL]
type="string"
[NODE_ENV]
type="enum"
values=["production", "development", "test"]
default="development"
required=true
[DATABASE_NAME]
type="string"
required=true
[WEBSITE_URL]
type="url"
required=true
deprecated=trueThe dotenvx CLI is installed automatically with the package.
Generates a .env file from your .envx:
npx dotenvx build| Option | Description | Default |
|---|---|---|
-i, --input |
Input .envx file |
.envx |
-o, --output |
Output .env file |
.env |
--overwrite |
Overwrite if exists | false |
Validates .envx against its declared schema:
npx dotenvx checkPrints the parsed and interpolated .envx as JSON:
npx dotenvx printGenerates a .ts file with full TypeScript typings based on the schema:
npx dotenvx types| Option | Description | Default |
|---|---|---|
-o, --output |
Output .ts file |
envx.ts |
You can create an optional envx.config.json in your project root to provide defaults for CLI options.
// envx.config.json (NEW)
{
input: ".envx",
outputs: {
env: ".env",
types: "src/envx.ts",
},
overwrite: true,
}If you want to use envx with TypeScript safely in your project:
// Load config
loadEnvx();
// Use with TS autocompletion
const env = getEnvx();If you're using npx dotenvx types, it will auto-generate typings you can import:
import { Env } from "./envx.ts";
const env: Env = getEnvx();dotenvx is fully compatible with the official VSCode extension for .envx files, which provides:
- Syntax highlighting
- Auto-completion
- Inline validation errors and warnings
- Hover tooltips for schema metadata such as
descriptionanddeprecated
Note: Fields like
descriptionanddeprecatedare only used by the VSCode extension for developer experience and do not affect runtime behavior or validation.
- Ternary & interpolation support
- CLI interface
- Type-safe runtime API
- Enum & default handling
- VSCode syntax plugin
- Web playground for
.envxfiles - Linting rules and formatting
MIT © Trymagic