or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

environment-loading.md environment-population.md file-parsing.md index.md vault-decryption.md

tile.json

Environment Loading

Core functionality for loading environment variables from .env files into process.env with intelligent handling of both standard and encrypted vault files.

Capabilities

Config Function

Main function that loads .env file contents into process.env. Automatically detects and handles encrypted .env.vault files when DOTENV_KEY is present.

/**
 * Loads .env file contents into process.env. If DOTENV_KEY is present, attempts to load encrypted .env.vault file
 * @param options - Configuration options for loading behavior
 * @returns Object with parsed values or error information
 */
function config(options?: DotenvConfigOptions): DotenvConfigOutput;

Usage Examples:

const dotenv = require('dotenv');

// Basic usage - loads .env from current directory
const result = dotenv.config();
if (result.error) {
  console.error('Error loading .env:', result.error);
} else {
  console.log('Loaded variables:', Object.keys(result.parsed));
}

// Custom path
dotenv.config({ path: './config/.env' });

// Multiple paths (processed in order, first file wins for duplicate keys)
dotenv.config({ path: ['.env.local', '.env.defaults'] });

// Override existing environment variables
dotenv.config({ override: true });

// Write to custom object instead of process.env
const myEnv = {};
dotenv.config({ processEnv: myEnv });
console.log(myEnv.DATABASE_URL);

// Enable debug logging
dotenv.config({ debug: true });

ConfigDotenv Function

Loads .env file contents into process.env. Does not handle encrypted vault files - only processes standard .env files.

/**
 * Loads .env file contents into process.env (standard files only)
 * @param options - Configuration options for loading behavior
 * @returns Object with parsed values or error information
 */
function configDotenv(options?: DotenvConfigOptions): DotenvConfigOutput;

Usage Examples:

const dotenv = require('dotenv');

// Force standard .env loading (ignores DOTENV_KEY)
const result = dotenv.configDotenv({ path: '.env' });

// Use when you want to ensure only standard .env files are processed
dotenv.configDotenv({ 
  path: ['.env.development', '.env'],
  debug: true 
});

Configuration Options

Path Options

Specify custom file paths for .env files.

interface PathOptions {
  /** Custom path to .env file or array of paths */
  path?: string | string[] | URL;
}

Examples:

// Single file
dotenv.config({ path: '/app/config/.env' });

// Multiple files (processed in order)
dotenv.config({ path: ['.env.local', '.env'] });

// Home directory expansion
dotenv.config({ path: '~/.env' });

// URL support
dotenv.config({ path: new URL('file:///app/.env') });

Encoding Options

Control file encoding for reading .env files.

interface EncodingOptions {
  /** File encoding (default: 'utf8') */
  encoding?: string;
}

Examples:

// Latin1 encoding
dotenv.config({ encoding: 'latin1' });

// Binary files
dotenv.config({ encoding: 'binary' });

Control Options

Control logging and override behavior.

interface ControlOptions {
  /** Suppress all output except errors (default: false) */
  quiet?: boolean;
  /** Enable debug logging (default: false) */
  debug?: boolean;
  /** Override existing environment variables (default: false) */
  override?: boolean;
}

Examples:

// Silent operation
dotenv.config({ quiet: true });

// Debug mode with detailed logging
dotenv.config({ debug: true });

// Override existing variables
dotenv.config({ override: true });

// Combined options
dotenv.config({ 
  debug: true, 
  override: true,
  quiet: false 
});

Target Options

Control where parsed variables are written.

interface TargetOptions {
  /** Target object to write variables to (default: process.env) */
  processEnv?: DotenvPopulateInput;
}

Examples:

// Write to custom object
const config = {};
dotenv.config({ processEnv: config });
console.log(config.DATABASE_URL);

// Isolated environment for testing
const testEnv = { ...process.env };
dotenv.config({ 
  processEnv: testEnv,
  path: '.env.test',
  override: true 
});

Vault Options

Configuration for encrypted .env.vault files.

interface VaultOptions {
  /** DOTENV_KEY for decrypting .env.vault files */
  DOTENV_KEY?: string;
}

Examples:

// Provide DOTENV_KEY directly
dotenv.config({ 
  DOTENV_KEY: 'dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=production' 
});

// Environment-based key (automatically detected)
// Set: DOTENV_KEY=dotenv://:key_1234@dotenvx.com/vault/.env.vault?environment=production
dotenv.config(); // Will use DOTENV_KEY from environment

Return Types

interface DotenvConfigOutput {
  /** Error object if loading failed */
  error?: Error;
  /** Parsed key-value pairs from .env file */
  parsed?: DotenvParseOutput;
}

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

Error Handling

Common errors and their meanings:

const result = dotenv.config();

if (result.error) {
  // File not found
  if (result.error.code === 'ENOENT') {
    console.log('.env file not found');
  }
  
  // Permission denied
  if (result.error.code === 'EACCES') {
    console.log('Permission denied reading .env file');
  }
  
  // Vault-specific errors
  if (result.error.code === 'INVALID_DOTENV_KEY') {
    console.log('Invalid DOTENV_KEY format');
  }
  
  if (result.error.code === 'DECRYPTION_FAILED') {
    console.log('Failed to decrypt .env.vault file');
  }
}

Version

Tile

Files