Guide

Note

@xpulse/dotenv is used internally by @xpulse/config only. You don't need to import it directly in your app code – @xpulse/config handles loading automatically.

Installation

1 npm install @xpulse/dotenv --registry=https://npm.xpulse.one

Quickstart

1 import dotenv from '@xpulse/dotenv';
2  
3 await dotenv.load();
4  
5 console.log(dotenv.get('PORT', '3000'));  // '3000'

Loading Files

dotenv.load() always loads .env as the base. Optionally an environment-specific file is loaded on top:

1 // Loads only .env
2 await dotenv.load();
3  
4 // Loads .env + .env.stage (stage overrides .env values)
5 await dotenv.load({ env: 'stage' });

If no env is provided, process.env.NODE_ENV is used as fallback. If that is also not set, only .env is loaded.

Load Order

1 1. .env          ← base
2 2. .env.{env}    ← overrides base values (if present)

Events

After loading, dotenv:loaded is emitted via @xpulse/event – but only if dotenv.useEvent() was called beforehand:

1 import event from '@xpulse/event';
2 import dotenv from '@xpulse/dotenv';
3  
4 dotenv.useEvent(event);
5 await dotenv.load({ env: 'stage' });
6  
7 // → emits: dotenv:loaded { env: 'stage', files: ['.env', '.env.stage'], override: false }

Loaded Files

1 dotenv.loaded;         // → true
2 dotenv.files;          // → ['.env', '.env.stage']

1	import dotenv from '@xpulse/dotenv';
2
3	await dotenv.load();
4
5	console.log(dotenv.get('PORT', '3000')); // '3000'

1	// Loads only .env
2	await dotenv.load();
3
4	// Loads .env + .env.stage (stage overrides .env values)
5	await dotenv.load({ env: 'stage' });

1	1. .env ← base
2	2. .env.{env} ← overrides base values (if present)

1	import event from '@xpulse/event';
2	import dotenv from '@xpulse/dotenv';
3
4	dotenv.useEvent(event);
5	await dotenv.load({ env: 'stage' });
6
7	// → emits: dotenv:loaded { env: 'stage', files: ['.env', '.env.stage'], override: false }

1	dotenv.loaded; // → true
2	dotenv.files; // → ['.env', '.env.stage']