CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-dotenv-expand

Expand environment variables using dotenv with support for variable interpolation and default values

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

index.mddocs/

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

Install with Tessl CLI

npx tessl i tessl/npm-dotenv-expand

docs

index.md

tile.json