home / skills / a5c-ai / babysitter / dotenv-integration

dotenv-integration skill

safe

/plugins/babysitter/skills/babysit/process/specializations/cli-mcp-development/skills/dotenv-integration

This skill helps you load and validate environment variables with dotenv, expand files, and type-coerce values for reliable configuration.

npx playbooks add skill a5c-ai/babysitter --skill dotenv-integration

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

916 B

---
name: dotenv-integration
description: Integrate dotenv for environment variable loading with validation and type coercion.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# Dotenv Integration

Integrate dotenv for environment variable loading.

## Generated Patterns

```typescript
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

Overview

This skill integrates dotenv-based environment loading with validation and type coercion to ensure reliable configuration at runtime. It combines dotenv, dotenv-expand, and Zod to load multiple .env files in a predictable order and to validate and coerce values into typed application settings. The result is a single exported env object your application can import with confidence.

How this skill works

The skill iterates through a prioritized list of .env files (for example: .env.local, .env.NODE_ENV, .env) and loads them using dotenv and dotenv-expand so variables and expansions are resolved. After loading, it runs a Zod schema against process.env to coerce types (numbers, enums) and to enforce required values and formats (URLs, non-empty strings). It exports the parsed and typed env object for direct consumption by the codebase.

When to use it

When you need deterministic, ordered loading of multiple .env files across environments.
When runtime configuration must be validated and fail-fast if values are missing or malformed.
When some environment values require type coercion (e.g., PORT -> number, FEATURE_FLAGS -> boolean).
During server bootstrap or CLI application initialization to prevent invalid runtime states.
In CI/CD or containerized deployments where explicit env validation avoids subtle bugs.

Best practices

Keep a minimal .env.example with types and defaults documented for developers.
Load .env files in a stable order: environment-specific, local overrides, then defaults.
Validate and coerce all public-facing configuration (ports, URLs, API keys) with a schema.
Provide sensible defaults in the schema to reduce required environment surface area.
Fail fast on schema parse errors to catch misconfiguration during startup.

Example use cases

Bootstrapping a microservice: load .env.production, validate DATABASE_URL and PORT, then start the server.
CLI tools that require typed flags from environment variables (timeouts as numbers, modes as enums).
Local developer experience: allow .env.local overrides while keeping shared .env as canonical defaults.
CI pipeline steps that validate deployment secrets and reject builds with missing or malformed secrets.

FAQ

What happens if an environment variable is missing or invalid?

The Zod schema parse will throw an error at startup, causing a fail-fast behavior so issues are detected immediately.

How are multiple .env files merged?

Files are loaded in the specified order and later values can overwrite earlier ones; dotenv-expand resolves nested references before validation.