Pages

Contents

@xpulse/app – Component Spec

Status: ACCEPTED · Updated March 2026 Parent: GLOBAL_concept-ecosystem.md

Overview

Entry point for every xPart. Bootstraps the entire stack via a resilient service loader and provides the app root as well as environment helpers.

Two responsibilities: bootstrap the stack + provide the app root – nothing more.

@xpulse/app is the only permitted place in the ecosystem that "knows everything". All other packages remain fully decoupled.

Dependencies

Two hard dependencies that are always required:

@xpulse/event — event bus (ADR-010)
@xpulse/config — loads xpulse.json + .env

The standard stack is shipped as dependencies for convenience and auto-discovered by the service loader at runtime: @xpulse/logger, @xpulse/http, @xpulse/router, @xpulse/template, @xpulse/theme, @xpulse/controller.

@xpulse/debug and @xpulse/dev are optional — no error if not installed. Feature packages (@xpulse/doc, etc.) are installed explicitly by the app.

API

app.init(env?)

Bootstraps the entire stack via the resilient service loader. Always everything – no selective loading.

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

app.start() / app.stop()

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

Typical 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

Value	Description
`development`	Local development
`stage`	Staging environment – RC testing
`production`	Production environment

Additional environments are allowed but undocumented. APP_ENV takes precedence over NODE_ENV.

App Root

The directory where xpulse.json lives – typically process.cwd(). Set on the first app.init() call and immutable thereafter.

All paths in the ecosystem are defined relative to the app root.

Helper Methods

app.root()

Returns the absolute app root path.

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

app.path(relative)

Resolves a relative path starting from the app root.

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

The current environment.

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

app.isDev()

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

app.isProd()

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

app.isStage()

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

Bootstrap Order

app.init() works via a auto-discovery service loader — packages declare their dependencies in xpulse.json, the loader resolves the correct init order via topological sort. See service-loader.md.

1 1. Set app root + config.load()    ← xpulse.json + .env
2 2. debug.bootstrapDebug()          ← only when debug.enabled
3                                       runs before loader so everything is debuggable
4 3. Service loader                  ← auto-discovers all installed @xpulse/* packages
5                                       with a service section in their xpulse.json
6                                       topological sort by depends[]
7                                       resilient: missing or disabled packages are skipped

@xpulse/event does not need an init() — zero dependencies, works on import. @xpulse/dev is a separate system — hooks in from the outside, loader ignores it.

Graceful Shutdown

1 1. Stop accepting new requests
2 2. Complete running requests (timeout: 30s)
3 3. Flush @xpulse/logger
4 4. process.exit(0)

Emitted Events

Event	Payload	When
`app:init`	`{ env, root }`	Bootstrap begins
`app:ready`	`{ env, root, uptime }`	Entire stack ready
`app:stopping`	`{ signal }`	SIGTERM / SIGINT received
`app:stopped`	`{ uptime, exitCode }`	Shutdown complete
`app:service:ready`	`{ service }`	Service initialised successfully
`app:service:skipped`	`{ service, reason }`	Not installed or `load: false`
`app:service:error`	`{ service, error }`	Init threw, loader continues

The complete event reference for all packages is in GLOBAL_adr-010-event-driven.md.

Receipt

@xpulse/app ships a receipt that is automatically executed on npm install.

receipt/up.js creates (only if not already present):

File	Contents
`src/index.js`	Minimal runnable app
`xpulse.json`	Minimal configuration (`name`, `type`)
`.npmrc`	Registry reference to `npm.xpulse.one`
`.env.example`	Documented example variables

receipt/down.js: Warning – no automatic deletion.

.env.example Contents

1 # xPulse App – Environment Variables
2 # Copy this file to .env and adjust the values
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

Package Structure

1 @xpulse/app/
2   src/
3     index.js          ← default export: app object
4     bootstrap/
5       app.js          ← app root + config.load()
6       services.js     ← auto-discovery service loader (reads 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 from APP_ENV → NODE_ENV → null
4	await app.init();
5
6	// explicit env
7	await app.init('stage');
8	await app.init('production');

1	app.start(); // blocking
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. Set app root + config.load() ← xpulse.json + .env
2	2. debug.bootstrapDebug() ← only when debug.enabled
3	runs before loader so everything is debuggable
4	3. Service loader ← auto-discovers all installed @xpulse/* packages
5	with a service section in their xpulse.json
6	topological sort by depends[]
7	resilient: missing or disabled packages are skipped

1	1. Stop accepting new requests
2	2. Complete running requests (timeout: 30s)
3	3. Flush @xpulse/logger
4	4. process.exit(0)

1	# xPulse App – Environment Variables
2	# Copy this file to .env and adjust the values
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 object
4	bootstrap/
5	app.js ← app root + config.load()
6	services.js ← auto-discovery service loader (reads 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