Boot sequence
Container discovery, adapter selection, lifecycle startup, and integration initialization.
Architecture
How xtaskjs boots, resolves routes, and extends security through one runtime.
This page focuses on the framework lifecycle: application bootstrap, request execution, and the security extension points layered onto the same controller pipeline.
Request path
Route lookup, guards, pipes, middlewares, handlers, and final adapter serialization.
Security layering
Strategies, auth services, decorators, and route context enrichment stay DI-aware.
Performance
Cache manifest, pool imports, lazy DI, and hot watcher reduce startup time 40–60%.
Quick Start
Boot the smallest useful xtask application
Install
npm install @xtaskjs/core @xtaskjs/common reflect-metadataBootstrap
import "reflect-metadata";
import { CreateApplication } from "@xtaskjs/core";
await CreateApplication({
adapter: "node-http",
autoListen: true,
server: { host: "127.0.0.1", port: 3000 },
});Bootstrap Flow
How xtaskjs wires the runtime
1. Define components
Decorate services, controllers, runners, and listeners in src/ so the container can discover them.
2. Call CreateApplication()
Core allocates the application lifecycle, kernel, and selected HTTP adapter.
3. Boot the kernel
The container scans project directories, registers providers, and resolves component metadata.
4. Attach integrations
Optional packages such as typeorm and security register lifecycle bindings into the same container.
5. Register routes and events
Controllers and listeners are translated into lifecycle routes, handlers, and execution pipelines.
6. Listen and serve
The selected adapter starts accepting requests and dispatches them back through the lifecycle.
Execution Flow
Request pipeline and security lifecycle
HTTP request lifecycle
Adapter receives request
Express, Fastify, or node-http normalizes the request and forwards method + path into the framework.
Route lookup
ApplicationLifeCycle resolves the controller route registered during startup.
Guards and auth
Guards can block or enrich the route context before the handler executes.
Pipes and middlewares
Arguments are transformed and cross-cutting logic runs in a consistent order.
Controller handler
The handler returns JSON, a primitive response, or a view(...) result.
Adapter response
The adapter serializes the payload, renders a view, or sends the appropriate status code.
Security extension lifecycle
Strategy registration
JWT or JWE strategies are registered before startup, defining token extraction and validation callbacks.
Security initialization
CreateApplication() initializes the security lifecycle and publishes auth services into the container.
Guard activation
Authenticated, Auth, Roles, and AllowAnonymous decorate routes and drive guard decisions.
Context enrichment
Successful authentication populates req.user, req.auth, response locals, and route execution context.
Performance
Startup optimizations and hot reload
Recent releases introduced several mechanisms that significantly reduce startup time and make local development faster. These work automatically once the package is installed.
Cache Manifest
On first boot the kernel scans src/ and writes .xtask-manifest.json. Subsequent starts load the manifest directly, skipping the filesystem scan entirely and reducing startup time by 40–60%.
Prebuilt Manifest
Running npm run build generates .xtask-manifest.prebuilt.json at compile time. Production starts load this file first, giving the fastest possible boot without any scanning.
Pool Imports Async
Discovered files are imported through a bounded semaphore pool. XTASK_IMPORT_CONCURRENCY (default 10) limits parallel imports to prevent filesystem saturation. Tune to 16–24 for larger apps.
Lazy DI Resolution
Constructor-injected dependencies are wrapped in transparent proxies and only instantiated on first access. Startup avoids creating services that are never called, reducing boot time for optional integrations.
Hot Manifest Watcher
In development, a file watcher applies incremental manifest updates. Changed files are re-imported and re-registered in the container without restarting the process.
Development mode
XTASK_IMPORT_CONCURRENCY=16 npm run devUse XTASK_IMPORT_CONCURRENCY to tune parallel file imports and let the hot watcher apply incremental updates without restarting.
Production mode
npm run build
npm startThe prebuilt manifest generated during npm run build is loaded first on every production start, skipping all scanning.