@xpulse/dotenv – Component Spec

Status: CONCEPT · Created March 2026 Parent: GLOBAL_concept-ecosystem.md

Overview

Loads .env files and populates process.env. Zero dependencies.

Not a wrapper around dotenv (npm) – a lean, custom implementation. Only what xPulse needs, no overhead.

API

Loading

1
import dotenv from '@xpulse/dotenv';
2
 
3
// Loads .env from the current working directory
4
await dotenv.load();
5
 
6
// Explicit path
7
await dotenv.load({ path: '/app/.env' });

Access

After dotenv.load() all values are available in process.env:

1
process.env.PORT       // '3000'
2
process.env.CHAT_URL   // 'https://chat.xpulse.one'

Additionally directly via dotenv:

1
dotenv.get('PORT')           // '3000'
2
dotenv.get('PORT', '8080')   // '3000' (fallback if not set)
3
dotenv.get('MISSING', '42')  // '42'

Introspection

1
// Has it already been loaded?
2
dotenv.loaded;
3
// → true

.env Format

Standard .env syntax:

1
# Comments are ignored
2
PORT=3000
3
CHAT_URL=https://chat.xpulse.one
4
 
5
# Quotes are stripped
6
APP_NAME="xPulse Web"
7
APP_NAME='xPulse Web'
8
 
9
# Empty lines are ignored
10
 
11
# Values with spaces require quotes
12
GREETING="Hello World"

Behaviour

• Existing process.env values are not overwritten — system environment takes precedence
• Comments (#) and empty lines are ignored
• Quotes (" and ') are stripped from values
• No interpolation (${VAR} in .env is not resolved — that is handled by @xpulse/config)

Package Structure

1
@xpulse/dotenv/
2
  index.js    ← default export: dotenv object
3
  README.md
4
  package.json

Dependencies

None.

Debug Integration

When @xpulse/debug is installed as a devDependency, @xpulse/dotenv automatically provides a DataCollector. @xpulse/debug discovers it via node_modules/@xpulse/dotenv/src/datacollectors/ – no configuration needed.

1
"optionalDependencies": {
2
  "@xpulse/debug": "^1.0.0"
3
}

The EnvCollector (name: 'env', icon: '🌍') shows in the Web Profiler:

• Loaded Files (list): all loaded .env files with their full path
• Process ENV (table): snapshot of all process.env entries at the time of the request with key and value

No toolbar badge.

Open Questions