.envx Syntax Reference

The .envx format is a typed, validated, and expressive environment configuration syntax designed as a modern replacement for legacy flat .env files. It enhances clarity, reduces runtime errors, and enables powerful editor tooling.

Key Concepts

• Typed values: Variables have explicit types such as string, number, boolean, enum, url, or email.
• Interpolation: Embed other variables dynamically using ${VAR_NAME} syntax.
• Conditional expressions (ternary): Inline logic to assign different values based on conditions.
• Schema section: Metadata and validation rules for variables, defined at the file’s end.

Variable Assignments

Variables are assigned as:

KEY=VALUE

Supported Value Types

• Strings: Quoted or unquoted text.
• Numbers: Numeric literals.
• Booleans: true or false.
• Multiline strings: Triple quotes """ enclose multi-line text.
• Expressions: Interpolations and ternary operators for dynamic values.

Interpolation

Interpolation lets you embed the value of one variable inside another, using the syntax:

API_URL=${BASE_URL}/api

Here, ${BASE_URL} will be replaced with the value of the BASE_URL variable at runtime.

💡 Tip: Variables referenced in interpolation must be defined earlier or in the same scope.

Conditional (Ternary) Expressions

You can use inline ternary operators to assign values based on a condition:

DEV_MODE=${NODE_ENV} == "development" ? true : false

Explanation:

• ${NODE_ENV} is interpolated to get the current environment value.
• The expression checks if NODE_ENV equals "development".
• If true, DEV_MODE becomes true.
• Otherwise, DEV_MODE is set to false.

This allows dynamic config based on environment:

API_URL=${DEV_MODE} ? "http://localhost:3000" : "https://api.example.com"

Schema Definition

At the bottom of the file, you define schema blocks that describe and validate variables:

[VARIABLE_NAME]
type = "string"
required = true
default = "defaultValue"
description = """Detailed documentation."""
values = ["allowed", "enum", "values"]
deprecated = false

⚠️ Important:

• Schema sections must be after all variable assignments.
• You cannot declare variables inside schema blocks.
• values is only valid if type="enum".

Supported Schema Properties

Property Details

type

Specifies the data type. Examples:

• string: Arbitrary text
• number: Numeric value
• boolean: true or false
• enum: One of the values array
• url: Valid URL format
• email: Valid email format

Example:

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

required

If true, the variable must be assigned or have a default, otherwise validation fails.

deprecated

Flags variables as obsolete. Useful to warn teams of upcoming removals.

description

Rich, multiline documentation for developer clarity and editor tooltips.

default

Fallback value if none assigned.

values

An array of allowed values, only valid with enum type.

Full Example

# Variable assignments
DEV_MODE=${NODE_ENV} == "development" ? true : false

PORT=8080
API_URL=${DEV_MODE} ? "http://localhost:${PORT}" : "https://api.example.com"
API_ENDPOINT="${DEV_MODE}/v1"

GREETING="Hello "user"!"
MULTILINE_EXAMPLE="""
I am .ENVX the best .env alternative!
"""

# Schema definitions (must be last)
[DEV_MODE]
type = "boolean"

[API_URL]
type = "url"
description = """Base URL for the API."""

[PORT]
type = "number"
required = true
description = "Port number the server listens on."

[GREETING]
type = "string"
description = """Welcome message displayed to users."""

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

[ANY_ARG2]
type = "string"
default = "any value"
required = true

Important Notes 🛠️

• Schema blocks must always appear after all variable assignments.
• Variables cannot be declared inside schema blocks.
• The values property applies only to enum types.
• description properties improve editor support and docs but do not affect runtime.
• deprecated flags help maintain backward compatibility and notify users.

This syntax empowers you to manage environment variables with strict typing, live validation, and rich editor support making your configs safer, clearer, and easier to maintain.