loadEnv

​

Function Signature

async function loadEnv(options?: LoadEnvOptions): Promise<LoadedEnv>

​

Parameters

​

Return Value

​

Loading Order

1. .env.${NODE_ENV}.local - Environment-specific local overrides
2. .env.${NODE_ENV} - Environment-specific variables
3. .env.local - Local overrides for all environments
4. .env - Default environment variables

​

Error Handling

• No environment variables could be loaded from any .env file
• All file reads failed (files don’t exist or are inaccessible)

​

Usage

​

Basic Usage

import { loadEnv } from "@natoboram/load_env"

await loadEnv()

// Environment variables are now available in process.env
console.log(process.env.DATABASE_URL)

​

Custom Directory

import { loadEnv } from "@natoboram/load_env"

await loadEnv({ path: "./config" })

// Loads .env files from the ./config directory

​

With Type-Safe Accessors

import { loadEnv, envString, envInt, envBool } from "@natoboram/load_env"

await loadEnv()

export const DATABASE_URL = envString("DATABASE_URL")
export const PORT = envInt("PORT", 3000)
export const DEBUG = envBool("DEBUG", false)

​

Setting NODE_ENV

// Set NODE_ENV before calling loadEnv
process.env.NODE_ENV = "production"

await loadEnv()

// Will load:
// - .env.production.local
// - .env.production
// - .env.local
// - .env

​

Example .env Files

​

.env

DATABASE_URL=postgresql://localhost:5432/myapp
PORT=3000
DEBUG=false

​

.env.development

DEBUG=true
DATABASE_URL=postgresql://localhost:5432/myapp_dev

​

.env.production

DATABASE_URL=postgresql://prod-server:5432/myapp
DEBUG=false
LOG_LEVEL=info

​

.env.local

# Local overrides (not committed to version control)
DATABASE_URL=postgresql://localhost:5432/my_local_db

​

Best Practices

1. Call Early: Call loadEnv() at the very beginning of your application before accessing any environment variables.
2. Don’t Commit Secrets: Add .env.local and .env.*.local files to .gitignore to avoid committing sensitive data.
3. Set NODE_ENV: Always set NODE_ENV in your environment before running your application, not in .env files.
4. Use Type-Safe Accessors: Use the provided type-safe accessor functions (envString, envInt, etc.) instead of directly accessing process.env.
5. Provide Defaults: Use default values for non-critical configuration to make your application more resilient.

​

Related Functions

• envString - Parse string environment variables
• envInt - Parse integer environment variables
• envBool - Parse boolean environment variables
• envUrl - Parse URL environment variables