What is the env loading order?

The files are loaded in this order: .env.local, .env.{NODE_ENV}, then .env, with later files overwriting earlier values.

How does missing variables get handled?

Variables with defaults (e.g., NODE_ENV, PORT) will default if not provided; required vars (e.g., DATABASE_URL, API_KEY) will cause a parse error and fail startup.

Can I customize the validation?

Yes. Extend or replace the envSchema in your bootstrap code to add more keys or adjust types with zod.

dotenv-integration

npx machina-cli add skill a5c-ai/babysitter/dotenv-integration --openclaw

Files (1)

SKILL.md

916 B

Dotenv Integration

Integrate dotenv for environment variable loading.

Generated Patterns

import { config } from 'dotenv';
import { expand } from 'dotenv-expand';
import { z } from 'zod';

// Load .env files in order
for (const file of ['.env.local', `.env.${process.env.NODE_ENV}`, '.env']) {
  expand(config({ path: file }));
}

const envSchema = z.object({
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  API_KEY: z.string().min(1),
});

export const env = envSchema.parse(process.env);

Target Processes

configuration-management-system
mcp-server-bootstrap
cli-application-bootstrap

Source

git clone https://github.com/a5c-ai/babysitter/blob/main/plugins/babysitter/skills/babysit/process/specializations/cli-mcp-development/skills/dotenv-integration/SKILL.md

View on GitHub

Overview

Loads environment variables from multiple .env files in a defined order and validates their types with zod, providing defaults where appropriate. It then exports a parsed env object for runtime use, ensuring startup safety and consistency.

How This Skill Works

The code loads three files in order using dotenv.config and dotenv-expand, then defines an envSchema with NODE_ENV, PORT, DATABASE_URL, and API_KEY. It uses envSchema.parse(process.env) to produce a typed env object that can be imported by the application.

When to Use It

Bootstrapping Node apps that rely on environment-specific config (.env.local / .env.{NODE_ENV} / .env)
Need type coercion (e.g., PORT) and defaults during startup
Require strict validation to fail fast if DATABASE_URL or API_KEY are missing or invalid
Bootstrapping CLI tools or services (e.g., configuration-management-system, mcp-server-bootstrap, cli-application-bootstrap)
Centralized, repeatable env loading across multiple services

Quick Start

Step 1: Install dependencies: npm i dotenv dotenv-expand zod
Step 2: Add the dotenv-integration snippet (env schema and parse) to your bootstrap file
Step 3: Import the parsed env (env) and use env.PORT, env.DATABASE_URL, etc.

Best Practices

Keep .env files out of source control and rely on defaults for safe startup
Validate at startup with envSchema.parse(process.env) to fail fast on errors
Use dotenv-expand to support variable expansion inside .env files
Leverage zod's coerce for numeric fields (PORT) and URL validation for DATABASE_URL
Document required vars (NODE_ENV, PORT, DATABASE_URL, API_KEY) and their expected formats

Example Use Cases

Web API service startup that uses PORT and DATABASE_URL from .env
CLI bootstrap for admin tooling with API_KEY required
Configuration-management-system bootstrap loading environment-specific settings
mcp-server-bootstrap initialization with environment defaults and validation
cli-application-bootstrap that relies on validated env for secure key handling

Frequently Asked Questions

Add this skill to your agents