Packages

@xtaskjs/common

Cross-package decorators, route metadata, logger, and shared execution types.

npm install @xtaskjs/common reflect-metadata Package path: packages/common

Overview

What this package owns in the runtime

Common provides the public decorator surface for controllers and route pipelines. It is the language the rest of the framework uses to express middleware, guard, and event metadata, and it includes the Logger used across adapters and services.

What it provides

Controller, Get, Post, Patch, Delete decorators describe routes.
UseGuards, UseMiddlewares, and UsePipes compose route execution order.
Logger and route metadata types are shared by framework packages.
Logger supports optional file persistence through logger.file.enabled and logger.file.path.
Logger output format includes app name, pid, optional context, and per-line delta time.
Lifecycle metadata drives runners and OnEvent listeners.

How it fits

Consumed by @xtaskjs/core during route registration and execution.
Extended by @xtaskjs/security through additional decorators and guards.
Often paired with request middleware that propagates a correlation id header for end-to-end tracing.

Usage Chart

How strongly this package shapes the runtime

Bootstrap

3/5

Dependency Injection

4/5

HTTP Delivery

5/5

Security

3/5

Integrations

4/5

Package Flow

How this package moves through xtaskjs runtime phases

Before startup

Common decorators attach route, guard, middleware, pipe, and lifecycle metadata while modules are imported.

During CreateApplication()

Core reads the metadata from @xtaskjs/common to register controller routes, lifecycle listeners, and execution pipelines.

During app.close()

Common itself does not hold resources, but its lifecycle metadata continues to shape how shutdown listeners run.

API Surface

Representative exports from the upstream package

Routing decorators

Controller
Get
Post
Patch
Delete
Body
Param
Query
Req
Res
UseGuards
UseMiddlewares
UsePipes

Lifecycle decorators

OnEvent
ApplicationRunner
CommandLineRunner

Validation and types

Logger
ValidationPipe
HANDLERS_KEY
ROUTES_KEY
RunnerMeta

Usage

Typical adoption flow

1. Define controllers

Use Controller, Get, Post, Patch, and Delete to describe the public HTTP surface of your application.

2. Compose the pipeline

Attach UseGuards, UseMiddlewares, and UsePipes to keep authentication, cross-cutting logic, and validation close to the route.

3. Add lifecycle hooks

Use ApplicationRunner, CommandLineRunner, and OnEvent when startup work or runtime events should be expressed with the same decorator-first model.

Example

Reference snippet

Controller metadata and pipeline composition

import { Controller, Get, Post, UseGuards } from "@xtaskjs/common";

@Controller("/users")
@UseGuards((context) => Boolean(context))
export class UsersController {
  @Get("/")
  list() {
    return [];
  }

  @Post("/")
  create() {
    return { created: true };
  }
}

Samples

Official samples to inspect next

Reference samples: All samples use controller decorators from @xtaskjs/common.