@xpulse/config – Component Spec

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

Übersicht

Liest und validiert xpulse.json, löst ${ENV_VAR} Referenzen auf und stellt die Konfiguration via config.get() bereit.

Eine Aufgabe: xpulse.json kennen und zugänglich machen – nicht mehr.

Dependencies

1 @xpulse/config
2   ├── @xpulse/dotenv   ← .env laden vor ${VAR} Auflösung
3   └── @xpulse/event    ← config:loaded feuern

API

Laden

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

Merge-Reihenfolge

config.load() baut die Konfiguration in drei Schichten auf:

1 1. Hardcoded DEFAULTS          ← niedrigste Priorität
2 2. node_modules/@xpulse/*/xpulse.json  ← alphabetisch gemergt
3 3. App-eigene xpulse.json      ← höchste Priorität, überschreibt alles

Alle installierten @xpulse/* Packages können so Default-Konfiguration mitliefern, die automatisch aktiv wird – ohne dass die App etwas konfigurieren muss. Die App-eigene xpulse.json hat immer Vorrang.

Beispiel: @xpulse/doc liefert alle Docs-Sources als Default mit. Wer eine Source deaktivieren will, setzt in der App-xpulse.json:

1 { "docs": { "sources": { "event": { "docs": false } } } }

Standard-Keys direkt

1 config.name    // 'xpulse-web'
2 config.type    // 'tool'

Alle Keys via get()

1 config.get('name')                  // 'xpulse-web'
2 config.get('type')                  // 'tool'
3 config.get('http.port')             // '3000'
4 config.get('theme.default')         // 'dark'
5 config.get('i18n.locales')          // ['de', 'en']
6 config.get('sources.chat.url')      // 'https://chat.xpulse.one'
7 config.get('release.current')       // '1.3.0'  (custom key)
8  
9 // Mit Fallback
10 config.get('http.port', '3000')     // Fallback wenn nicht gesetzt
11 config.get('missing.key', null)     // null

Vollständiges Objekt

1 config.all();
2 // → vollständiges Objekt mit Fallbacks und aufgelösten ${VAR} Werten

${ENV_VAR} Auflösung

xpulse.json kann auf .env Werte referenzieren:

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

config.load() löst alle ${VAR} Referenzen auf – nach @xpulse/dotenv Laden:

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

Nicht aufgelöste Variablen (nicht in .env und nicht in process.env) bleiben als ${VAR} stehen und erzeugen eine Warnung.

Fallback-Werte (Konvention)

Key	Fallback
`type`	`'tool'`
`theme.default`	`'dark'`
`i18n.default`	`'de'`
`i18n.locales`	`['de']`
`paths.templates`	`'src/templates/'`
`paths.locales`	`'src/locales/'`
`paths.public`	`'src/public/'`
`http.port`	`process.env.PORT \|\| '3000'`
`sources.*.docs`	`false`
`sources.*.type`	`'tool'`

Validierung

config.load() validiert bekannte Standard-Keys:

Fehler	Verhalten
`xpulse.json` nicht gefunden	wirft `Error`
Ungültiges JSON	wirft `Error`
`name` fehlt	wirft `Error`
Unbekannte Keys	ignoriert, keine Warnung
`${VAR}` nicht auflösbar	Warnung, Wert bleibt `${VAR}`

Gefeuerte Events

Event	Payload	Wann
`config:loaded`	`{ name, type, env, files, packages }`	nach erfolgreichem `config.load()`

1 import event from '@xpulse/event';
2  
3 event.on('config:loaded', ({ name, type, env, files, packages }) => {
4     // name     – App-Name aus xpulse.json
5     // type     – 'tool' | 'component' | ...
6     // env      – NODE_ENV
7     // files    – geladene Dateien [xpulse.json, .env, ...]
8     // packages – gemergete Package-Configs ['@xpulse/doc', '@xpulse/theme', ...]
9 });

Debug Integration

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

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

Der ConfigCollector (name: 'config', icon: '🔧') zeigt im Web Profiler:

Summary (kv): Name, Type, ENV (NODE_ENV bzw. APP_ENV), Debug-Config, HTTP Port, Log Enabled, Log Level
Full Config (resolved) (raw): der vollständige config.all() Output als formatiertes JSON – inklusive DEFAULTS und aufgelöster ${ENV_VAR} Werte

Objekt-Werte in der Summary (z.B. der debug-Block) werden als JSON serialisiert. Kein Toolbar-Badge.

Paket-Struktur

1 @xpulse/config/
2   src/
3     index.js      ← default export: config-Objekt
4     defaults.js   ← Fallback-Werte (intern)
5     resolver.js   ← ${VAR} Auflösung (intern)
6     validator.js  ← Standard-Keys validieren (intern)
7   test/
8     config.test.js
9     resolver.test.js
10     validator.test.js
11   docs/
12     index.md
13     api.md
14     _meta.json
15   Dockerfile
16   Makefile
17   README.md
18   package.json
19   xpulse.json

1	@xpulse/config
2	├── @xpulse/dotenv ← .env laden vor ${VAR} Auflösung
3	└── @xpulse/event ← config:loaded feuern

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

1	1. Hardcoded DEFAULTS ← niedrigste Priorität
2	2. node_modules/@xpulse/*/xpulse.json ← alphabetisch gemergt
3	3. App-eigene xpulse.json ← höchste Priorität, überschreibt alles

1	config.get('name') // 'xpulse-web'
2	config.get('type') // 'tool'
3	config.get('http.port') // '3000'
4	config.get('theme.default') // 'dark'
5	config.get('i18n.locales') // ['de', 'en']
6	config.get('sources.chat.url') // 'https://chat.xpulse.one'
7	config.get('release.current') // '1.3.0' (custom key)
8
9	// Mit Fallback
10	config.get('http.port', '3000') // Fallback wenn nicht gesetzt
11	config.get('missing.key', null) // null

1	config.all();
2	// → vollständiges Objekt mit Fallbacks und aufgelösten ${VAR} Werten

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

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

1	import event from '@xpulse/event';
2
3	event.on('config:loaded', ({ name, type, env, files, packages }) => {
4	// name – App-Name aus xpulse.json
5	// type – 'tool' \| 'component' \| ...
6	// env – NODE_ENV
7	// files – geladene Dateien [xpulse.json, .env, ...]
8	// packages – gemergete Package-Configs ['@xpulse/doc', '@xpulse/theme', ...]
9	});

1	@xpulse/config/
2	src/
3	index.js ← default export: config-Objekt
4	defaults.js ← Fallback-Werte (intern)
5	resolver.js ← ${VAR} Auflösung (intern)
6	validator.js ← Standard-Keys validieren (intern)
7	test/
8	config.test.js
9	resolver.test.js
10	validator.test.js
11	docs/
12	index.md
13	api.md
14	_meta.json
15	Dockerfile
16	Makefile
17	README.md
18	package.json
19	xpulse.json