loony-dotenv

A tiny, zero-dependency utility for loading .env files into process.env.

Installation

npm install loony-dotenv

Usage

ESM

import { loadEnv } from "loony-dotenv";

loadEnv(); // loads "./.env"

CommonJS

const { loadEnv } = require("loony-dotenv");

loadEnv();

Example .env file

PORT=3000
DB_HOST=localhost          # inline comment — stripped
DB_NAME="my database"      # spaces preserved inside quotes
GREETING="hello\nworld"    # \n, \t, \r expanded in double-quoted values
API_KEY='secret-key'       # single quotes — no escape expansion
QUERY=select\=1            # escaped = in value

API

loadEnv(envPath?, options?)

Reads a .env file and populates process.env. Returns a Record<string, string> of the variables that were actually set (pre-existing variables that were not overridden are excluded).

loadEnv(envPath?: string, options?: LoadEnvOptions): Record<string, string>

| Parameter | Type | Default | Description | |---|---|---|---| | envPath | string | ".env" | Path to the .env file | | options.override | boolean | false | When true, overwrites variables already in process.env |

// Load a custom path
loadEnv("./config/production.env");

// Force-overwrite any existing variables
loadEnv(".env", { override: true });

// Inspect what was loaded
const loaded = loadEnv();
console.log(loaded); // { PORT: "3000", DB_HOST: "localhost", ... }

getEnv(key, defaultValue?)

Typed accessor for process.env. Returns the value, falls back to defaultValue, or throws if the variable is missing and no default is given.

getEnv(key: string, defaultValue?: string): string

import { loadEnv, getEnv } from "loony-dotenv";

loadEnv();

const port = getEnv("PORT", "8080");   // returns "8080" if PORT is not set
const host = getEnv("DB_HOST");        // throws if DB_HOST is not set

Parsing rules

| Input | Result | |---|---| | KEY=value | "value" | | KEY=value # comment | "value" (comment stripped) | | KEY="value # not a comment" | "value # not a comment" | | KEY="line1\nline2" | "line1\nline2" (newline) | | KEY='line1\nline2' | "line1\nline2" (literal backslash-n) | | KEY=val\=ue | "val=ue" | | # comment | skipped | | blank line | skipped | | =value | skipped (empty key) | | BADLINE | skipped (no =) |

License

ISC © Sankar Boro