or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

environment-loading.mdenvironment-population.mdfile-parsing.mdindex.mdvault-decryption.md
tile.json

tessl/npm-dotenv

Loads environment variables from .env file into process.env with support for encrypted .env.vault files

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/dotenv@17.2.x

To install, run

npx @tessl/cli install tessl/npm-dotenv@17.2.0

index.mddocs/

Dotenv

Dotenv is a zero-dependency Node.js module that loads environment variables from .env files into process.env. It supports both standard .env files and encrypted .env.vault files for secure deployments, following The Twelve-Factor App methodology for configuration management.

Package Information

  • Package Name: dotenv
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install dotenv

Core Imports

const dotenv = require('dotenv');

For ES6 modules:

import dotenv from 'dotenv';

Auto-configuration (loads .env automatically):

require('dotenv/config');

Or for ES6:

import 'dotenv/config';

Basic Usage

// Basic usage - loads .env from current directory
require('dotenv').config();

console.log(process.env.DATABASE_URL); // logs your env var
console.log(process.env.SECRET_KEY);   // logs your env var

// With custom path
require('dotenv').config({ path: '/custom/path/to/.env' });

// With multiple paths (processed in order)
require('dotenv').config({ path: ['.env.local', '.env'] });

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

Architecture

Dotenv is built around several key components:

  • Configuration Loading: Main config() function handles both standard and encrypted .env files
  • Parser Engine: parse() function converts .env file contents to JavaScript objects
  • Population System: populate() function merges parsed values into environment objects
  • Encryption Support: Transparent handling of .env.vault files with DOTENV_KEY
  • Flexible Options: Support for multiple files, custom encoding, debug logging, and override behavior

Capabilities

Environment Loading

Core functionality for loading environment variables from .env files into process.env with support for encrypted vault files.

function config(options?: DotenvConfigOptions): DotenvConfigOutput;
function configDotenv(options?: DotenvConfigOptions): DotenvConfigOutput;

Environment Loading

File Parsing

Low-level parsing functionality for converting .env file contents into JavaScript objects without modifying process.env.

function parse<T extends DotenvParseOutput = DotenvParseOutput>(
  src: string | Buffer
): T;

File Parsing

Environment Population

Utility for merging parsed environment variables into target objects like process.env with flexible override options.

function populate(
  processEnv: DotenvPopulateInput,
  parsed: DotenvPopulateInput,
  options?: DotenvPopulateOptions
): DotenvPopulateOutput;

Environment Population

Vault Decryption

Support for encrypted .env.vault files using AES-256-GCM encryption for secure deployments.

function decrypt(encrypted: string, keyStr: string): string;

Vault Decryption

Environment Options

Utility module that reads dotenv configuration from environment variables for auto-configuration scenarios.

// Exported as an object with configuration options parsed from environment variables
const envOptions: DotenvConfigOptions;

Import:

const envOptions = require('dotenv/lib/env-options');

Environment Variables:

  • DOTENV_CONFIG_ENCODING → options.encoding
  • DOTENV_CONFIG_PATH → options.path
  • DOTENV_CONFIG_QUIET → options.quiet
  • DOTENV_CONFIG_DEBUG → options.debug
  • DOTENV_CONFIG_OVERRIDE → options.override
  • DOTENV_CONFIG_DOTENV_KEY → options.DOTENV_KEY

CLI Options

Utility module that parses dotenv configuration from command-line arguments.

// Function that parses command-line arguments into configuration options
function parseCliOptions(args: string[]): DotenvConfigOptions;

Import:

const parseCliOptions = require('dotenv/lib/cli-options');

Usage:

// Parse command-line arguments
const options = parseCliOptions(process.argv);
// Supports: dotenv_config_encoding=utf8 dotenv_config_path=.env.local

Configuration Types

interface DotenvConfigOptions {
  path?: string | string[] | URL;
  encoding?: string;
  quiet?: boolean;
  debug?: boolean;
  override?: boolean;
  processEnv?: DotenvPopulateInput;
  DOTENV_KEY?: string;
}

interface DotenvConfigOutput {
  error?: Error;
  parsed?: DotenvParseOutput;
}

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

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

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

interface DotenvPopulateOptions {
  debug?: boolean;
  override?: boolean;
}