README.md

June 3, 2026 · View on GitHub

Tresdoce NestJS Toolkit

Este toolkit está pensado para ser utilizado en NestJS Starter, o cualquier proyecto que utilice una configuración centralizada, siguiendo la misma arquitectura del starter.

Glosario

Demo
Requerimientos básicos
Arquitectura y configuración centralizada
Interfaz AppConfig
Grafo de dependencias entre paquetes
Scripts
Toolkit
Commits
License MIT

Requerimientos básicos

NestJS Starter
Node.js v22.21.1 or higher (Download)
YARN >= 1.22.22 o NPM >= 11.6.4
NestJS v11.1.11 or higher (Documentación)
Lerna

Arquitectura y configuración centralizada

Todos los paquetes de este toolkit siguen un patrón de configuración centralizada: en lugar de que cada módulo reciba su configuración de forma independiente, todos leen desde un único ConfigService de NestJS bajo la clave 'config'.

Cómo funciona

La aplicación host registra una función de configuración usando registerAs de @nestjs/config:

// configuration.ts
import { registerAs } from '@nestjs/config';
import { Typings } from '@tresdoce-nestjs-toolkit/core';

export default registerAs('config', (): Typings.AppConfig => ({
  project: { ... },
  server: { ... },
  swagger: { ... },
  redis: { ... },    // leído por @tresdoce-nestjs-toolkit/redis
  mailer: { ... },   // leído por @tresdoce-nestjs-toolkit/mailer
  // ...demás secciones opcionales
}));

Cada paquete de este toolkit inyecta ConfigService y accede únicamente a su propia sección del objeto config:

// Ejemplo interno de RedisModule
@Injectable()
export class RedisService {
  constructor(private readonly configService: ConfigService) {}

  getOptions() {
    return this.configService.get<Typings.AppConfig>('config').redis;
  }
}

La interfaz AppConfig (exportada por @tresdoce-nestjs-toolkit/core bajo el namespace Typings) es el contrato central que garantiza la coherencia de tipos entre todos los paquetes.

Ventajas del patrón

Un solo punto de verdad: toda la configuración vive en configuration.ts.
Tipado end-to-end: AppConfig valida en tiempo de compilación que cada sección tenga la forma correcta.
Modularidad real: agregar o quitar un módulo equivale a agregar o quitar una clave del objeto de configuración.
Compatible con schematics: los paquetes están diseñados para instalarse mediante ng add / schematics del NestJS Starter.

Interfaz AppConfig

La siguiente interfaz, definida en packages/core/src/typings/index.ts y exportada como Typings.AppConfig, es el contrato que une a todos los paquetes del toolkit.

// @tresdoce-nestjs-toolkit/core — Typings.AppConfig
interface AppConfig {
  // REQUERIDO — metadatos de la aplicación (leídos del package.json del proyecto host)
  project: {
    apiPrefix: string;
    name: string;
    version: string;
    description: string;
    author: { name: string; email: string; url: string };
    repository: { type: string; url: string };
    bugs: { url: string };
    homepage: string;
    [key: string]: any;
  };

  // REQUERIDO — configuración de runtime del servidor
  server: {
    isProd: boolean;
    appStage: 'local' | 'test' | 'snd' | 'dev' | 'qa' | 'homo' | 'prod';
    port: number;
    context: string;
    origins: string[] | string;
    propagateHeaders?: string[]; // -> response-parser
    exposedHeaders?: string;
    allowedHeaders: string;
    allowedMethods: string;
    corsEnabled: boolean;
    corsCredentials: boolean;
    csrf?: CsrfCookieOptions; // -> @tresdoce-nestjs-toolkit/core
    rateLimits?: ThrottlerModuleOptions; // -> @tresdoce-nestjs-toolkit/rate-limit
  };

  // REQUERIDO — configuración de Swagger/OpenAPI
  swagger: {
    path: string;
    enabled: boolean;
  };

  // OPCIONAL — configuración de health checks
  // -> @tresdoce-nestjs-toolkit/health
  health?: {
    skipChecks?: ('storage' | 'memory' | 'elasticsearch' | 'camunda' | 'typeorm' | 'redis')[];
    storage?: DiskHealthIndicatorOptions;
    memory?: { heap: number; rss: number };
  };

  // OPCIONAL — servicios externos para health checks de conectividad HTTP
  // -> @tresdoce-nestjs-toolkit/health
  services?: Record<
    string,
    {
      url: string;
      timeout?: number;
      healthPath?: string;
      [key: string]: any;
    }
  >;

  // OPCIONAL — configuración del cliente HTTP (Axios + axios-retry)
  // -> @tresdoce-nestjs-toolkit/http-client
  httpClient?: {
    httpOptions?: HttpModuleOptions;
    propagateHeaders?: string[];
  };

  // OPCIONAL — configuración de base de datos relacional vía TypeORM
  // -> @tresdoce-nestjs-toolkit/typeorm
  database?: {
    typeorm?: TypeOrmModuleOptions;
  };

  // OPCIONAL — configuración de Redis para cache
  // -> @tresdoce-nestjs-toolkit/redis
  redis?: RedisOptions;

  // OPCIONAL — configuración del mailer (nodemailer)
  // -> @tresdoce-nestjs-toolkit/mailer
  mailer?: MailerOptions;

  // OPCIONAL — configuración de Camunda (BPMN)
  // -> @tresdoce-nestjs-toolkit/camunda
  camunda?: CamundaOptions;

  // OPCIONAL — configuración de Elasticsearch
  // -> @tresdoce-nestjs-toolkit/elk
  elasticsearch?: ElasticsearchOptions;

  // OPCIONAL — configuración de trazabilidad distribuida (OpenTelemetry)
  // -> @tresdoce-nestjs-toolkit/tracing
  tracing?: TracingOptions;

  // OPCIONAL — configuración de redacción de campos sensibles en logs
  // -> @tresdoce-nestjs-toolkit/utils (RedactModule)
  redact?: RedactOptions;

  // OPCIONAL — configuración de hashing con bcrypt
  // -> @tresdoce-nestjs-toolkit/utils (BcryptModule)
  bcrypt?: BcryptOptions;

  // OPCIONAL — configuración de generación de IDs únicos tipo Snowflake
  // -> @tresdoce-nestjs-toolkit/snowflake-uid
  snowflakeUID?: SnowFlakeOptions;

  // OPCIONAL — configuración de AWS Simple Queue Service
  // -> @tresdoce-nestjs-toolkit/aws-sqs
  sqs?: AwsSqsModuleOptions;

  // OPCIONAL — parámetros personalizados de la aplicación
  params?: Record<string, any>;

  [key: string]: any;
}

Grafo de dependencias entre paquetes

El siguiente diagrama muestra las dependencias internas entre los paquetes del toolkit (dependencias hacia paquetes externos de npm no se muestran).

graph TD
  core["core\n(tipos base, decoradores, CSRF)"]
  utils["utils\n(Redact, Format, Bcrypt)"]
  filters["filters\n(ExceptionsFilter)"]
  tracing["tracing\n(OpenTelemetry)"]
  elk["elk\n(Elasticsearch)"]
  health["health\n(liveness/readiness)"]
  archetype["archetype\n(endpoint /info)"]
  httpClient["http-client\n(Axios wrapper)"]
  responseParser["response-parser\n(ResponseInterceptor)"]
  paas["paas\n(umbrella cross)"]
  rateLimits["rate-limit\n(ThrottlerModule)"]

  filters --> core
  tracing --> utils
  elk --> utils
  elk --> filters
  health --> core
  health --> tracing
  archetype --> core
  httpClient --> core
  responseParser --> filters
  paas --> core
  paas --> filters
  paas --> health
  paas --> responseParser
  paas --> tracing
  paas --> utils
  paas --> rateLimits

Paquetes standalone (sin dependencias internas entre si): aws-sqs, camunda, commons, dynamoose, mailer, qrcode, rate-limit, redis, snowflake-uid, typeorm, test-utils.

Scripts

Instalar Lerna

npm i -g lerna

Instalar dependencias del monorepo

yarn install

Crear paquetes

yarn plop

Transpilar paquetes

yarn build

Test paquetes

yarn test

Toolkit

Los módulos de la siguiente lista están pensados para ser consumidos por el NestJS Starter, siguiendo los lineamientos de schematics.

Es recomendable utilizar las versiones estables, ya que las versiones beta están pensadas para ser utilizadas a modo de testing y pueden generar conflictos en el código.

Package	Descripción	Clave AppConfig	Changelog
`@tresdoce-nestjs-toolkit/archetype`	Módulo informativo de la app	`config.project.*`, `config.server.appStage`	Changelog
`@tresdoce-nestjs-toolkit/aws-sqs`	Módulo de cola de mensajes de AWS Simple Queue Service	`config.sqs`	Changelog
`@tresdoce-nestjs-toolkit/camunda`	Módulo de procesos BPMN con Camunda	`config.camunda`	Changelog
`@tresdoce-nestjs-toolkit/commons`	Centralización de configuraciones de build y ESLint	(configuración de herramientas, no de app)	Changelog
`@tresdoce-nestjs-toolkit/core`	Tipos base (`AppConfig`), decoradores y helpers de CSRF	(contrato central, no lee config)	Changelog
`@tresdoce-nestjs-toolkit/dynamoose`	Módulo de base de datos DynamoDB con Dynamoose	(configuración propia, no usa AppConfig)	Changelog
`@tresdoce-nestjs-toolkit/elk`	Módulo de ElasticSearch Stack	`config.elasticsearch`	Changelog
`@tresdoce-nestjs-toolkit/filters`	Filtro global de excepciones HTTP	(inyectado directamente, sin clave config)	Changelog
`@tresdoce-nestjs-toolkit/health`	Health checks de liveness y readiness	`config.health`, `config.services`	Changelog
`@tresdoce-nestjs-toolkit/http-client`	Cliente HTTP con Axios y axios-retry	`config.httpClient`	Changelog
`@tresdoce-nestjs-toolkit/mailer`	Módulo para envíos de mail	`config.mailer`	Changelog
`@tresdoce-nestjs-toolkit/paas`	Librería centralizada de funcionalidades cross (umbrella)	múltiples (ver paquetes que agrupa)	Changelog
`@tresdoce-nestjs-toolkit/qrcode`	Módulo para crear códigos QR	(configuración propia, no usa AppConfig)	Changelog
`@tresdoce-nestjs-toolkit/rate-limit`	Limitador de requests por segundo en controllers	`config.server.rateLimits`	Changelog
`@tresdoce-nestjs-toolkit/redis`	Módulo de Redis para cache	`config.redis`	Changelog
`@tresdoce-nestjs-toolkit/response-parser`	Interceptor de formateo de respuesta	`config.server.propagateHeaders`	Changelog
`@tresdoce-nestjs-toolkit/snowflake-uid`	Módulo de generación de IDs únicos tipo Snowflake	`config.snowflakeUID`	Changelog
`@tresdoce-nestjs-toolkit/test-utils`	Utilities para testing	(utilidades de test, no usa AppConfig)	Changelog
`@tresdoce-nestjs-toolkit/tracing`	Módulo de trazabilidad distribuida con OpenTelemetry	`config.tracing`	Changelog
`@tresdoce-nestjs-toolkit/typeorm`	Módulo de ORM para base de datos relacional	`config.database.typeorm`	Changelog
`@tresdoce-nestjs-toolkit/utils`	Utilitarios para proyectos y librerías	`config.redact`, `config.bcrypt`	Changelog

Commits

Para los mensajes de commits se toma como referencia conventional commits.

<type>[optional scope]: <description>

[optional body]

[optional footer]

type: chore, docs, feat, fix, refactor, test (más comunes)
scope: indica la página, componente, funcionalidad
description: comienza en minúsculas y no debe superar los 72 caracteres.

Ejemplo Commit

git commit -m "docs(core): add documentantion to readme core module"

Commit Breaking Change

git commit -am 'feat!: changes in application'

Made with ❤️