Syntax Reference

Typenv uses the .envx format — an extended superset of traditional .env — to describe environment variables with types, defaults, validation, descriptions, and conditions.

This document is a comprehensive guide to writing correct and expressive .envx files.

Basics

Each environment variable is defined just like a traditional .env file:

API_URL = "https://api.example.com"
PORT = 8080

You can then define metadata using a [BLOCK] syntax at the end:

[PORT]
type = "number"
required = true
description = "Port your app will run on"

Supported Types

Typenv supports the following primitive types:

string
number
boolean
url
email
enum

Examples:

[PORT]
type = "number"

[IS_PROD]
type = "boolean"

[SUPPORT_EMAIL]
type = "email"

[API_ENDPOINT]
type = "url"

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

String Interpolation

Like shell or templates, variables can be referenced in other values:

API_URL = "https://api.example.com"
FULL_URL = "${API_URL}/v1"

Expressions

Typenv supports conditional expressions and ternary operators.

DEV_MODE = ${NODE_ENV} == "development" ? true : false
BASE_URL = ${DEV_MODE} ? "http://localhost:3000" : "https://prod.example.com"

This makes environment logic self-contained and declarative.

Multiline Strings

Use triple double-quotes """ to define multiline string values:

MULTILINE = """
This is a multiline value.
You can include newlines and special characters.
"""

You can also include nested quotes inside:

EXAMPLE = """
String with a triple quote:  \"\"\"
"""

Escaping

Use \ to escape quotes or special characters inside strings.

GREETING = "Hello \"user\"!"

Descriptions

Descriptions can span multiple lines and also use triple-quoted blocks.

[PASSWORD]
type = "string"
description = """
The password used for encryption.
This field should be kept secure.
"""

Required, Default, and Enum

You can control validation using:

required = true
default = "some-value"
values = ["a", "b", "c"]

[MODE]
type = "enum"
values = ["on", "off"]
default = "off"
required = true

Comments

You can add inline or block comments with #:

# This is a comment
PORT = 8080 # Inline comment

Special Case: NODE_ENV

If you don't explicitly declare NODE_ENV, it automatically inherits from the current process environment.

# Will be true if NODE_ENV is "development"
DEV_MODE = ${NODE_ENV} == "development" ? true : false

Full Example

DEV_MODE = ${NODE_ENV} == "development" ? true : false
API_URL = ${DEV_MODE} ? "http://localhost:3000" : "https://api.example.com"
TOKEN = ${DEV_MODE} ? "dev-token" : "prod-token"
FULL_API_URL = "${API_URL}?token=${TOKEN}"

[DEV_MODE]
type = "boolean"
default = false

[API_URL]
type = "url"
required = true

[TOKEN]
type = "string"
required = true

[FULL_API_URL]
type = "url"

Best Practices

✅ Use default values where possible
✅ Always define types explicitly
✅ Group schema blocks at the bottom
✅ Use descriptive variable names
✅ Document complex variables with multiline descriptions

What is Valid .envx?

A valid .envx file:

Defines key=value pairs
Uses interpolation with ${VAR_NAME}
Has a schema block for each variable
Uses supported types and directives only
Contains no runtime JS, only declarative config

Basic Syntax Reference