Anleitung

Installation

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

Quickstart

1 import config from '@xpulse/config';
2  
3 await config.load();
4  
5 console.log(config.name);              // 'xpulse-web'
6 console.log(config.get('http.port'));  // '3000'

Was passiert beim Laden?

config.load() führt folgende Schritte in dieser Reihenfolge aus:

dotenv.load() – lädt .env + .env.{NODE_ENV} ins process.env
xpulse.json lesen und parsen
name validieren – Error wenn nicht gesetzt
Fallbacks einsetzen – fehlende Standard-Keys werden mit Defaults befüllt
${VAR} auflösen – alle Referenzen auf process.env Werte werden ersetzt
config:loaded feuern

xpulse.json anlegen

Jedes Projekt braucht eine xpulse.json im Repo-Root:

1 {
2   "name": "xpulse-web",
3   "type": "tool"
4 }

name ist Pflicht – alle anderen Keys sind optional und haben Fallbacks.

${ENV_VAR} Referenzen

Werte in xpulse.json können auf .env Variablen referenzieren:

1 {
2   "name": "xpulse-web",
3   "type": "tool",
4   "http": {
5     "port": "${PORT}"
6   },
7   "sources": {
8     "chat": {
9       "url": "${CHAT_URL}"
10     }
11   }
12 }

1 # .env
2 PORT=3000
3 CHAT_URL=https://chat.xpulse.one

1 await config.load();
2 config.get('http.port')        // '3000'
3 config.get('sources.chat.url') // 'https://chat.xpulse.one'

Nicht auflösbare Variablen bleiben als ${VAR} stehen und erzeugen eine Warnung.

Custom Keys

xpulse.json ist ein offenes Schema – eigene Keys sind erlaubt und werden ohne Warnung durchgereicht:

1 {
2   "name": "xpulse-chat",
3   "type": "tool",
4   "release": {
5     "current":  "1.3.0",
6     "codename": "Abomasnow"
7   }
8 }

1 config.get('release.current')   // '1.3.0'
2 config.get('release.codename')  // 'Abomasnow'

Events

Nach config.load() wird config:loaded via @xpulse/event emittiert. dotenv:loaded wird kurz davor von @xpulse/dotenv gefeuert.

1 import event from '@xpulse/event';
2  
3 event.on('config:loaded', ({ name, type, env, files }) => {
4     console.log(`${name} (${type}) geladen – ENV: ${env}`);
5 });
6  
7 await config.load();

Expliziter Pfad

1 // xpulse.json aus anderem Verzeichnis laden
2 await config.load({ path: '/app' });
3  
4 // Bestimmtes Environment erzwingen
5 await config.load({ env: 'stage' });

1	import config from '@xpulse/config';
2
3	await config.load();
4
5	console.log(config.name); // 'xpulse-web'
6	console.log(config.get('http.port')); // '3000'

1	{
2	"name": "xpulse-web",
3	"type": "tool",
4	"http": {
5	"port": "${PORT}"
6	},
7	"sources": {
8	"chat": {
9	"url": "${CHAT_URL}"
10	}
11	}
12	}

1	await config.load();
2	config.get('http.port') // '3000'
3	config.get('sources.chat.url') // 'https://chat.xpulse.one'

1	{
2	"name": "xpulse-chat",
3	"type": "tool",
4	"release": {
5	"current": "1.3.0",
6	"codename": "Abomasnow"
7	}
8	}

1	config.get('release.current') // '1.3.0'
2	config.get('release.codename') // 'Abomasnow'

1	import event from '@xpulse/event';
2
3	event.on('config:loaded', ({ name, type, env, files }) => {
4	console.log(`${name} (${type}) geladen – ENV: ${env}`);
5	});
6
7	await config.load();

1	// xpulse.json aus anderem Verzeichnis laden
2	await config.load({ path: '/app' });
3
4	// Bestimmtes Environment erzwingen
5	await config.load({ env: 'stage' });