@xpulse/dotenv – Component Spec

Status: CONCEPT · Erstellt März 2026 Übergeordnet: GLOBAL_concept-ecosystem.md

Übersicht

Lädt .env Dateien und befüllt process.env. Zero dependencies.

Kein Wrapper um dotenv (npm) – eigene, schlanke Implementierung. Nur was xPulse braucht, kein Overhead.

API

Laden

1
import dotenv from '@xpulse/dotenv';
2
 
3
// Lädt .env aus dem aktuellen Arbeitsverzeichnis
4
await dotenv.load();
5
 
6
// Expliziter Pfad
7
await dotenv.load({ path: '/app/.env' });

Zugriff

Nach dotenv.load() sind alle Werte in process.env verfügbar:

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

Zusätzlich direkt über dotenv:

1
dotenv.get('PORT')           // '3000'
2
dotenv.get('PORT', '8080')   // '3000' (Fallback wenn nicht gesetzt)
3
dotenv.get('MISSING', '42')  // '42'

Introspection

1
// Wurde bereits geladen?
2
dotenv.loaded;
3
// → true

.env Format

Standard .env Syntax:

1
# Kommentare werden ignoriert
2
PORT=3000
3
CHAT_URL=https://chat.xpulse.one
4
 
5
# Anführungszeichen werden entfernt
6
APP_NAME="xPulse Web"
7
APP_NAME='xPulse Web'
8
 
9
# Leerzeilen werden ignoriert
10
 
11
# Werte mit Leerzeichen brauchen Anführungszeichen
12
GREETING="Hello World"

Verhalten

• Bestehende process.env Werte werden nicht überschrieben — System-Env hat Vorrang
• Kommentare (#) und Leerzeilen werden ignoriert
• Anführungszeichen (" und ') werden vom Wert entfernt
• Keine Interpolation (${VAR} in .env wird nicht aufgelöst — das macht @xpulse/config)

Paket-Struktur

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

Dependencies

Keine.

Debug Integration

Wenn @xpulse/debug als devDependency installiert ist, stellt @xpulse/dotenv automatisch einen DataCollector bereit. @xpulse/debug discovert ihn via node_modules/@xpulse/dotenv/src/datacollectors/ – keine Konfiguration nötig.

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

Der EnvCollector (name: 'env', icon: '🌍') zeigt im Web Profiler:

• Loaded Files (list): alle geladenen .env-Dateien mit vollständigem Pfad
• Process ENV (table): Snapshot aller process.env-Einträge zum Zeitpunkt des Requests mit Key und Wert

Kein Toolbar-Badge.

Offene Fragen