dotenv

dotenv

Load environment variables from .env files for Andromeda applications.

This module provides a complete implementation for working with .env files, supporting advanced features like variable expansion, default values, multi-line strings, and more. The dotenv module is based off of the deno dotenv module see https://jsr.io/@std/dotenv

Usage

Auto-load from .env file

The simplest way to use dotenv is to import the load.ts module, which automatically loads variables from .env into the process environment:

// At the top of your main application file
import "https://tryandromeda.dev/std/dotenv/load.ts";

// Now you can access variables from .env
console.log(Andromeda.env.get("DATABASE_URL"));
console.log(Andromeda.env.get("API_KEY"));

With a .env file like:

# Database Configuration
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=secret123
PORT=3000

Manual loading

For more control, use the load() or loadSync() functions:

import { load, loadSync } from "https://tryandromeda.dev/std/dotenv/mod.ts";

// Async loading
const config = await load();
console.log(config.DATABASE_URL);

// Sync loading
const configSync = loadSync();
console.log(configSync.DATABASE_URL);

// Export to environment
await load({ export: true });
console.log(Andromeda.env.get("DATABASE_URL"));

Custom .env file paths

import { load } from "https://tryandromeda.dev/std/dotenv/mod.ts";

// Load from a custom path
const prodConfig = await load({
  envPath: ".env.production",
  export: true,
});

// Load multiple environments
const devConfig = await load({ envPath: ".env.development" });
const localConfig = await load({ envPath: ".env.local" });

// Merge configurations
const config = { ...devConfig, ...localConfig };

Parse .env strings

import { parse } from "https://tryandromeda.dev/std/dotenv/mod.ts";

const envString = `
  DATABASE_URL=postgresql://localhost:5432/mydb
  REDIS_URL=redis://localhost:6379
  # This is a comment
  APP_NAME="My Application"
`;

const config = parse(envString);
console.log(config);
// {
//   DATABASE_URL: "postgresql://localhost:5432/mydb",
//   REDIS_URL: "redis://localhost:6379",
//   APP_NAME: "My Application"
// }

Stringify objects to .env format

import { stringify } from "https://tryandromeda.dev/std/dotenv/mod.ts";

const config = {
  DATABASE_URL: "postgresql://localhost:5432/mydb",
  API_KEY: "secret123",
  MESSAGE: "Hello\nWorld",
};

const envContent = stringify(config);
console.log(envContent);
// DATABASE_URL='postgresql://localhost:5432/mydb'
// API_KEY=secret123
// MESSAGE="Hello\nWorld"

// Write to file
await Andromeda.writeTextFile(".env.backup", envContent);

Validate against example file

import { loadSync } from "https://tryandromeda.dev/std/dotenv/mod.ts";

// This will throw an error if required variables are missing
const config = loadSync({
  envPath: ".env",
  examplePath: ".env.example",
  export: true,
});

.env File Format

Basic syntax

# Comments start with #
KEY=value
QUOTED='single quoted value'
DOUBLE_QUOTED="double quoted value"

# Export prefix is supported
export EXPORTED_VAR=value

Variable expansion

Variables can reference other variables or environment variables:

HOST=localhost
PORT=5432
DATABASE=mydb

# Reference other variables
DATABASE_URL=postgresql://$HOST:$PORT/$DATABASE
# Or with braces
DATABASE_URL=postgresql://${HOST}:${PORT}/${DATABASE}

# Use default values if variable doesn't exist
BACKUP_URL=${BACKUP_HOST:-localhost}/backup
LOG_LEVEL=${LOG_LEVEL:-info}

Multi-line values

Use double quotes for multi-line values:

PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7
-----END PRIVATE KEY-----"

MESSAGE="Hello
World
From
Multiple
Lines"

Escape sequences

Double-quoted values support escape sequences:

NEWLINE="Line 1\nLine 2\nLine 3"
TAB="Column1\tColumn2\tColumn3"
RETURN="Carriage\rReturn"
QUOTE="He said \"Hello\""

Special characters

# Simple values don't need quotes
SIMPLE_VALUE=123
ALPHANUMERIC=abc123

# Values with special characters should be quoted
SPECIAL='value with spaces'
URL='https://example.com?foo=bar&baz=qux'
JSON='{"key": "value", "nested": {"foo": "bar"}}'