@edirect/nest-app

Opinionated NestJS application bootstrapper for eDirect services. Provides a single bootstrap() function that wires up NestJS with eDirect conventions: environment loading, Swagger documentation, global pipes/filters, session, CORS, XML body parsing, and MongoDB migrations — out of the box.

Features

• One-function startup with bootstrap(AppModule, options)
• Swagger/OpenAPI docs auto-configured at /documentation
• Global ValidationPipe with transform + whitelist
• Global HttpExceptionFilter for consistent error responses
• Optional CORS, trust proxy, XML body parsing, static assets
• API versioning support
• Custom global interceptors
• Auto-runs MongoDB migrations on startup (via migrate-mongo)
• Microservice support via microservice() helper

Installation

pnpm add @edirect/nest-app
# or
npm install @edirect/nest-app

Quick Start

// main.ts
import { bootstrap } from '@edirect/nest-app';
import { AppModule } from './app.module';

bootstrap(AppModule, {
  port: 3000,
  title: 'Payment Gateway',
  description: 'Handles payment processing',
  version: '1.0',
  tag: 'payments',
});

AppOptionsInterface

All options are optional. APP_PORT environment variable is used as fallback for port.

| Option | Type | Description | |--------|------|-------------| | port | number | Port to listen on (falls back to APP_PORT env) | | configPath | string | Path to .env file (default: .{NODE_ENV}.env) | | title | string | Swagger title (falls back to APP_TITLE env) | | description | string | Swagger description (falls back to APP_DESCRIPTION env) | | version | string | Swagger version (falls back to APP_VERSION env) | | tag | string | Swagger tag (falls back to APP_TAG env) | | enableCors | boolean | Enable CORS | | corsConfig | CorsOptions | CORS configuration options | | trustProxy | boolean | Enable trust proxy + secure session | | disableGlobalFilter | boolean | Disable the default HttpExceptionFilter | | interceptors | NestInterceptor[] | Global interceptors to register | | validation | ValidationPipeOptions | Additional ValidationPipe options | | bodyInputLimitInMb | number | Body size limit in MB | | parseXml | boolean | Enable XML body parsing | | staticPath | string | Path to serve static assets from | | versioning | boolean \| VersioningOptions | Enable API versioning | | swaggerCustomDocuments | SwaggerCustomDocuments[] | Additional Swagger documents at custom paths |

Environment Variables

| Variable | Description | |----------|-------------| | APP_PORT | Server port | | APP_TITLE | Swagger title | | APP_DESCRIPTION | Swagger description | | APP_VERSION | Swagger version | | APP_TAG | Swagger tag | | KEYCLOAK_BASE_URL | If set, adds OpenID Connect bearer auth to Swagger | | KEYCLOAK_REALM | Keycloak realm (used for Swagger OpenID Connect URL) |

Decorators

@edirect/nest-app exports several useful decorators for service routing patterns:

| Decorator | Description | |-----------|-------------| | @Country() | Injects country from request context | | @Destination() | Marks a class as a destination service | | @DestinationHeaders() | Extracts destination headers | | @DestinationPath() | Sets path for destination routing | | @DestinationPrefix() | Sets prefix for destination routing | | @DestinationRequest() | Marks a method as a destination request handler | | @DestinationRequestKeyMapper() | Maps request keys | | @DestinationResponseKeyMapper() | Maps response keys | | @UsePreflight() | Adds a preflight middleware step | | @UsePostflight() | Adds a postflight middleware step |

Exceptions

| Class | Description | |-------|-------------| | HttpServiceException | Wraps HTTP errors from downstream services | | NotFoundException | Standard 404 exception |

Filters

| Class | Description | |-------|-------------| | HttpExceptionFilter | Converts NestJS HTTP exceptions to standard response format | | ServiceExceptionFilter | Converts HttpServiceException to HTTP responses |

Interceptors

| Class | Description | |-------|-------------| | AppInterceptor | General-purpose application interceptor | | ServiceInterceptor | Wraps service responses in standard format |

Microservice Bootstrap

For NestJS microservices:

import { microservice } from '@edirect/nest-app';
import { AppModule } from './app.module';

microservice(AppModule, {
  port: 3001,
});

Healthcheck Module

Built-in healthcheck endpoint available via HealthcheckModule:

import { Module } from '@nestjs/common';
import { HealthcheckModule } from '@edirect/nest-app'; // internal module

@Module({
  imports: [HealthcheckModule],
})
export class AppModule {}

Exposes GET /health with configurable health providers.