Skip to main content
@natoboram/load_env is a standalone implementation of Vite’s loadEnv function that provides a simple and type-safe way to manage environment variables in your Node.js applications.

​
What is Load Env?

Load Env helps you:
  • Load environment variables from .env files automatically
  • Ensure type safety with dedicated functions for different data types
  • Handle secrets from the filesystem (Docker Compose secrets support)
  • Provide fallback values for environment variables
  • Parse complex types like URLs, UUIDs, dates, and enums

​
Key Features

Automatic Loading

Automatically loads .env files based on NODE_ENV with proper precedence handling

Type Safety

Type-safe functions for booleans, numbers, strings, URLs, UUIDs, dates, and more

Secret Management

Built-in support for Docker Compose secrets and filesystem-based secrets

Fallback Support

Provide default values for environment variables that might not be set

​
How It Works

Load Env follows a simple loading strategy based on NODE_ENV:
1

Set NODE_ENV

The NODE_ENV environment variable determines which .env files to load. If not set, it defaults to development.
2

Load .env files

Environment variables are loaded in order of precedence:
  1. .env.${NODE_ENV}.local (highest priority)
  2. .env.${NODE_ENV}
  3. .env.local
  4. .env (lowest priority)
3

Merge with process.env

Loaded variables are merged with existing process.env values, with process.env taking precedence.
NODE_ENV must be set in the environment and will not be picked up from .env files.

​
Example Usage

Here’s a quick example of how to use Load Env: 
import { loadEnv, envString, envInt, envBool } from "@natoboram/load_env"

// Load environment variables from .env files
await loadEnv()

// Use type-safe functions to access variables
export const PORT = envInt("PORT", 3000)
export const DATABASE_URL = envString("DATABASE_URL")
export const DEBUG = envBool("DEBUG", false)

​
When to Use Load Env

Node.js Applications

Perfect for backend applications, CLI tools, and scripts that need environment configuration

Docker Deployments

Seamless integration with Docker Compose secrets for secure credential management

Multiple Environments

Easy management of development, staging, and production configurations

Type-Safe Config

Applications that benefit from compile-time type checking of configuration values

​
Next Steps

Installation

Install Load Env in your project via npm, yarn, pnpm, or JSR

Quick Start

Get started with a working example in minutes

Build docs developers (and LLMs) love

Get started for freeTalk to us