String Interpolation in .envx

String interpolation allows you to dynamically reference the value of one environment variable inside another within your .envx configuration files. This feature enables modular, maintainable, and DRY environment definitions by avoiding repetition and allowing variables to build on each other.

How Interpolation Works

In .envx files, Variables can reference other variables by using the "${KEY}" syntax inside their values. These references will be resolved during parsing.

For example:

API_BASE_URL = "https://api.example.com"
LOGIN_ENDPOINT = "${API_BASE_URL}/auth/login"

Here, LOGIN_ENDPOINT uses the value of API_BASE_URL as its base and appends /auth/login to construct the full URL.

Key Characteristics

• Order matters: Referenced variables must be declared before they are used to ensure proper resolution.
• Recursive interpolation: Variables can chain references, e.g.:

HOST = "example.com"
API_BASE_URL = "https://${HOST}/api"
LOGIN_URL = "${API_BASE_URL}/login"

• Safe cycle detection: Circular references are detected and throw a validation error to prevent infinite loops.
• Supports all string values: You can interpolate inside quoted strings, plain strings, or even in complex expressions.

Practical Examples

Simple Reference

APP_NAME = "MyApp"
WELCOME_MSG = "Welcome to ${APP_NAME}!"

Result:
WELCOME_MSG becomes "Welcome to MyApp!"

Nested Interpolation

DOMAIN = "example.com"
API_HOST = "https://api.\${DOMAIN}"
FULL_URL = "${API_HOST}/v1/resources"

Result:
FULL_URL becomes "https://api.example.com/v1/resources"

Interpolation with Defaults and Ternary

DOMAIN = "example.com"
API_HOST = "https://api.\${DOMAIN}"
PROD_URL = "${API_HOST}/v1/resources"
ENV = "production"
API_ENDPOINT = ${ENV} == "production" ? "${PROD_URL}" : "http://localhost:3000"

💡 Tip: You can combine interpolation with ternary expressions to create different behaviors for development vs production environments.

Common Pitfalls

• Undefined variables: Referencing a variable that is not declared earlier results in an error during validation.
• Circular references: For example, A = "\${B}" and B = "\${A}" will throw a cycle detection error.
• Order sensitivity: Define variables in logical order to avoid undefined references.

Built-in System Environment Variables

Some variables like ${NODE_ENV}, ${CI}, or ${VERCEL_ENV} are automatically available during parsing — even if they are not defined inside the .envx file.

These are known as whitelisted system variables, and they won't raise a "Reference to undefined key" error during validation.

Supported system variables include:

• NODE_ENV
• CI
• VERCEL_ENV
• etc.

✅ You can safely reference them like ${NODE_ENV} without explicitly declaring them inside the file.

❌ If you reference a non-existent or typo'd key (e.g. ${NODE_ENVV}), validation will still throw an error unless it's in the supported list.

Example

NODE_ENV = "production"
API_BASE = ${NODE_ENV} == "production" ? "https://api.example.com" : "http://localhost:3000"

If NODE_ENV was not declared in the file, it would still be recognized as valid.

Important Notes on Variable Declaration Order and Cycles

While .envx interpolation allows referencing other variables even if they are declared later, it is highly recommended to declare variables before using them to ensure smooth resolution and better readability.

Our parser is designed to handle most cases flexibly, so referencing a variable before declaration does not immediately cause an error. However, when variables form deeply nested or circular references, problems arise:

API_KEY1 = "${API_KEY2}"
API_KEY2 = "${API_KEY3}"
API_KEY3 = "${API_KEY1}"
... +10

The above forms a circular dependency, which will cause an infinite resolution loop and thus a parsing error.

Similarly, a variable referencing itself directly:

API_KEY1 = "${API_KEY1}"

also causes an infinite loop error.

Our parser detects these cycles and will throw a validation error when such references exist to prevent runtime issues.

Best Practices

• Declaring variables before use is best practice for clarity and safer resolution.
• Use interpolation to avoid duplicating URLs, paths, or other repeated strings.
• Combine with ternary and default operators to create flexible environment setups.
• [IMPORTANT] Circular or self-referencing variables cause infinite loops and parsing errors.
• [IMPORTANT] Deeply nested complex references (10+ levels intertwined irregularly) may also trigger errors.
• Always validate .envx files after changes to catch any problematic references early.

Summary

String interpolation in .envx is a powerful tool for crafting dynamic, maintainable, and expressive environment configurations. It reduces redundancy, improves readability, and enables complex value compositions without sacrificing clarity.

Use it wisely to keep your environment setups clean and efficient.