or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

dotenv-expand

dotenv-expand adds variable expansion on top of dotenv, enabling environment variables to reference other environment variables using ${VAR} or $VAR syntax. It supports advanced expansion features including default values, self-referential checking to prevent infinite loops, and escape sequence handling for secure environment variable management.

Package Information

Package Name: dotenv-expand
Package Type: npm
Language: JavaScript with TypeScript definitions
Installation: npm install dotenv-expand

Core Imports

const dotenvExpand = require('dotenv-expand');

Or with destructuring:

const { expand } = require('dotenv-expand');

For TypeScript/ES modules:

import { expand } from 'dotenv-expand';

Basic Usage

const dotenv = require('dotenv');
const dotenvExpand = require('dotenv-expand');

// Basic usage - expand variables from dotenv
dotenvExpand.expand(dotenv.config());

console.log(process.env.DB_PASS); // Expanded from .env file

Example .env file:

PASSWORD="s1mpl3"
DB_PASS=$PASSWORD
DOMAIN="${HOST:-localhost}:${PORT:-3000}"

Capabilities

Variable Expansion

Expands environment variables in parsed dotenv data with support for multiple syntax patterns and safety features.

/**
 * Expands environment variables in parsed dotenv data
 * @param options - Configuration options for expansion
 * @returns Result object with expanded variables or error
 */
function expand(options?: DotenvExpandOptions): DotenvExpandOutput;

interface DotenvExpandOptions {
  /** Error from previous dotenv operations */
  error?: Error;
  /** Target environment object (default: process.env) */
  processEnv?: DotenvPopulateInput;
  /** Parsed data from dotenv to expand */
  parsed?: DotenvParseInput;
}

interface DotenvExpandOutput {
  /** Error if expansion failed */
  error?: Error;
  /** Expanded environment variables */
  parsed?: DotenvParseOutput;
}

Usage Examples:

const dotenv = require('dotenv');
const dotenvExpand = require('dotenv-expand');

// Standard usage with dotenv
const config = dotenv.config();
const expandedConfig = dotenvExpand.expand(config);

// Custom environment object
const myEnv = {};
const result = dotenvExpand.expand({
  processEnv: myEnv,
  parsed: {
    API_KEY: 'secret123',
    API_URL: 'https://api.example.com/${API_KEY}'
  }
});

// With error handling
const config = dotenv.config();
if (config.error) {
  console.error('dotenv error:', config.error);
} else {
  const expanded = dotenvExpand.expand(config);
  if (expanded.error) {
    console.error('expansion error:', expanded.error);
  }
}

Configuration Preload

Preload script that automatically runs dotenv.config() and expansion in one step.

# Command line usage
node -r dotenv-expand/config your_script.js

# With custom path
node -r dotenv-expand/config your_script.js dotenv_config_path=/custom/.env

# With environment variables
DOTENV_CONFIG_PATH=/custom/.env node -r dotenv-expand/config your_script.js

Variable Expansion Syntax

Basic Variable Expansion

Braced: ${VARIABLE} - Expands to value of VARIABLE
Unbraced: $VARIABLE - Expands to value of VARIABLE
Escaped: \$VARIABLE - Literal $VARIABLE (no expansion)

Default Value Operators

${VAR:-default} - Use default if VAR is unset or empty
${VAR-default} - Use default if VAR is unset (empty is valid)
${VAR:+alternate} - Use alternate if VAR is set and not empty
${VAR+alternate} - Use alternate if VAR is set (even if empty)

Examples:

# .env file
BASE_URL="https://api.example.com"
API_VERSION="v1"
API_ENDPOINT="${BASE_URL}/${API_VERSION}/users"

# Default values
DEBUG_MODE="${DEBUG:-false}"
PORT="${PORT:-3000}"

# Alternate values
ENV_SUFFIX="${NODE_ENV:+.${NODE_ENV}}"
CONFIG_FILE="config${ENV_SUFFIX}.json"

# Escaped values
DATABASE_PASSWORD="pa\\$\\$word"  # Results in "pa$$word"

Types

interface DotenvPopulateInput {
  [name: string]: string;
}

interface DotenvParseInput {
  [name: string]: string;
}

interface DotenvParseOutput {
  [name: string]: string;
}

Error Handling

The expand function preserves errors from dotenv operations and can generate its own expansion errors:

const config = dotenv.config({ path: 'missing-file.env' });
const result = dotenvExpand.expand(config);

if (result.error) {
  console.error('Configuration error:', result.error.message);
}

Security Features

Self-reference protection: Prevents infinite recursion when variables reference themselves
Escape sequences: Use \$ to include literal dollar signs without expansion
Process.env priority: Existing process.env values take precedence over .env file values
No process.env expansion: As of v12.0.0, pre-existing process.env variables are not expanded for security