Seiten

Inhalt

@xpulse/app – Component Spec

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

Übersicht

Einstiegspunkt für jeden xPart. Bootstrapped den gesamten Stack über einen resilienten Service Loader und stellt den App Root sowie Environment-Helpers bereit.

Zwei Aufgaben: Stack bootstrappen + App Root bereitstellen – nicht mehr.

@xpulse/app ist der einzige erlaubte Ort im Ökosystem der "alles kennt". Alle anderen Packages bleiben vollständig entkoppelt.

Dependencies

Zwei harte Dependencies die immer benötigt werden:

@xpulse/event — Event Bus (ADR-010)
@xpulse/config — lädt xpulse.json + .env

Der Standard-Stack wird als Dependencies mitgeliefert und vom Service Loader zur Laufzeit auto-discovert: @xpulse/logger, @xpulse/http, @xpulse/router, @xpulse/template, @xpulse/theme, @xpulse/controller.

@xpulse/debug und @xpulse/dev sind optional — kein Fehler wenn nicht installiert. Feature-Packages (@xpulse/doc etc.) werden von der App selbst installiert.

API

app.init(env?)

Bootstrapped den gesamten Stack über den resilienten Service Loader. Immer alles – kein selektives Laden.

1 import app from '@xpulse/app';
2  
3 // env aus APP_ENV → NODE_ENV → null
4 await app.init();
5  
6 // env explizit
7 await app.init('stage');
8 await app.init('production');

app.start() / app.stop()

1 app.start();       // blockierend
2 await app.stop();  // graceful shutdown

Typische index.js

1 import app from '@xpulse/app';
2  
3 await app.init();
4 app.start();
5  
6 process.on('SIGTERM', () => app.stop());
7 process.on('SIGINT',  () => app.stop());

Environments

Wert	Beschreibung
`development`	Lokale Entwicklung
`stage`	Staging-Umgebung – RC Testing
`production`	Produktiv-Umgebung

Weitere Environments sind erlaubt aber undokumentiert. APP_ENV hat Vorrang vor NODE_ENV.

App Root

Das Verzeichnis in dem xpulse.json liegt – in der Regel process.cwd(). Wird beim ersten app.init() gesetzt und ist danach unveränderlich.

Alle Pfade im Ökosystem sind relativ zum App Root definiert.

Helper Methoden

app.root()

Gibt den absoluten App Root Pfad zurück.

1 app.root()
2 // → '/var/www/my-app'

app.path(relative)

Löst einen relativen Pfad ausgehend vom App Root auf.

1 app.path('src/templates')       // → '/var/www/my-app/src/templates'
2 app.path('var/cache/template')  // → '/var/www/my-app/var/cache/template'
3 app.path('var/log')             // → '/var/www/my-app/var/log'

app.env

Das aktuelle Environment.

1 app.env  // → 'stage' | 'production' | 'development' | null

app.isDev()

1 app.isDev()    // → true wenn env === 'development'

app.isProd()

1 app.isProd()   // → true wenn env === 'production'

app.isStage()

1 app.isStage()  // → true wenn env === 'stage'

Bootstrap-Reihenfolge

app.init() arbeitet über einen Auto-Discovery Service Loader — Packages deklarieren ihre Abhängigkeiten in xpulse.json, der Loader ermittelt die richtige Init-Reihenfolge per Topological Sort. Siehe service-loader.md.

1 1. App Root + config.load()        ← xpulse.json + .env laden
2 2. debug.bootstrapDebug()          ← nur wenn debug.enabled
3                                       läuft vor dem Loader damit alles debuggbar ist
4 3. Service Loader                  ← auto-discovert alle installierten @xpulse/*-Packages
5                                       mit service-Section in ihrer xpulse.json
6                                       Topological Sort nach depends[]
7                                       resilient: fehlende oder deaktivierte Packages werden übersprungen

@xpulse/event braucht kein init() — zero-dependencies, funktioniert sofort beim Import. @xpulse/dev ist ein eigenes System — klinkt sich von außen ein, Loader ignoriert es.

Graceful Shutdown

1 1. Keine neuen Requests mehr annehmen
2 2. Laufende Requests abschließen (Timeout: 30s)
3 3. @xpulse/logger flushen
4 4. process.exit(0)

Gefeuerte Events

Event	Payload	Wann
`app:init`	`{ env, root }`	Bootstrap beginnt
`app:ready`	`{ env, root, uptime }`	Gesamter Stack bereit
`app:stopping`	`{ signal }`	SIGTERM / SIGINT empfangen
`app:stopped`	`{ uptime, exitCode }`	Shutdown abgeschlossen
`app:service:ready`	`{ service }`	Service erfolgreich initialisiert
`app:service:skipped`	`{ service, reason }`	Nicht installiert oder `load: false`
`app:service:error`	`{ service, error }`	Init hat geworfen, Loader macht weiter

Die vollständige Event-Referenz aller Packages ist in GLOBAL_adr-010-event-driven.md.

Receipt

@xpulse/app bringt ein Receipt mit das bei npm install automatisch ausgeführt wird.

receipt/up.js legt an (nur wenn nicht vorhanden):

Datei	Inhalt
`src/index.js`	Minimale lauffähige App
`xpulse.json`	Minimale Konfiguration (`name`, `type`)
`.npmrc`	Registry-Verweis auf `npm.xpulse.one`
`.env.example`	Dokumentierte Beispiel-Variablen

receipt/down.js: Warnung – keine automatische Löschung.

.env.example Inhalt

1 # xPulse App – Environment Variables
2 # Kopiere diese Datei nach .env und passe die Werte an
3  
4 # Server
5 PORT=3000
6  
7 # Environment: development | stage | production
8 APP_ENV=development
9  
10 # Logging
11 LOG=true
12 DEBUG=false

Paket-Struktur

1 @xpulse/app/
2   src/
3     index.js          ← default export: app-Objekt
4     bootstrap/
5       app.js          ← App Root + config.load()
6       services.js     ← Auto-Discovery Service Loader (liest xpulse.json, Topo-Sort)
7   receipt/
8     up.js
9     down.js
10     files/
11       src/
12         index.js
13       xpulse.json
14       .npmrc
15       .env.example
16   test/
17     app.test.js
18   docs/
19     index.md
20     de/ index, guide, api
21     en/ index, guide, api
22   Dockerfile
23   Makefile
24   README.md
25   package.json
26   xpulse.json

1	import app from '@xpulse/app';
2
3	// env aus APP_ENV → NODE_ENV → null
4	await app.init();
5
6	// env explizit
7	await app.init('stage');
8	await app.init('production');

1	app.start(); // blockierend
2	await app.stop(); // graceful shutdown

1	import app from '@xpulse/app';
2
3	await app.init();
4	app.start();
5
6	process.on('SIGTERM', () => app.stop());
7	process.on('SIGINT', () => app.stop());

1	app.path('src/templates') // → '/var/www/my-app/src/templates'
2	app.path('var/cache/template') // → '/var/www/my-app/var/cache/template'
3	app.path('var/log') // → '/var/www/my-app/var/log'

1	1. App Root + config.load() ← xpulse.json + .env laden
2	2. debug.bootstrapDebug() ← nur wenn debug.enabled
3	läuft vor dem Loader damit alles debuggbar ist
4	3. Service Loader ← auto-discovert alle installierten @xpulse/*-Packages
5	mit service-Section in ihrer xpulse.json
6	Topological Sort nach depends[]
7	resilient: fehlende oder deaktivierte Packages werden übersprungen

1	1. Keine neuen Requests mehr annehmen
2	2. Laufende Requests abschließen (Timeout: 30s)
3	3. @xpulse/logger flushen
4	4. process.exit(0)

1	# xPulse App – Environment Variables
2	# Kopiere diese Datei nach .env und passe die Werte an
3
4	# Server
5	PORT=3000
6
7	# Environment: development \| stage \| production
8	APP_ENV=development
9
10	# Logging
11	LOG=true
12	DEBUG=false

1	@xpulse/app/
2	src/
3	index.js ← default export: app-Objekt
4	bootstrap/
5	app.js ← App Root + config.load()
6	services.js ← Auto-Discovery Service Loader (liest xpulse.json, Topo-Sort)
7	receipt/
8	up.js
9	down.js
10	files/
11	src/
12	index.js
13	xpulse.json
14	.npmrc
15	.env.example
16	test/
17	app.test.js
18	docs/
19	index.md
20	de/ index, guide, api
21	en/ index, guide, api
22	Dockerfile
23	Makefile
24	README.md
25	package.json
26	xpulse.json