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

Centraliza configuraciones de ESLint, Jest, Webpack y herramientas de build que son comunes a todos los paquetes del monorepo y proyectos derivados.

Glosario

• 🥳 Demo
• 📝 Requerimientos básicos
• 🛠️ Instalar dependencia
• 👨‍💻 Uso
  • ESLint config
  • Jest config
  • Webpack config
  • CLI Starter Webpack config
  • buildConfig
• 📖 API Reference
• 📄 Changelog
• 📜 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)

🛠️ Instalar dependencia

Este paquete es una dependencia de desarrollo (devDependency).

npm install -D @tresdoce-nestjs-toolkit/commons

yarn add -D @tresdoce-nestjs-toolkit/commons

Peer dependencies requeridas para ESLint

El uso de eslintConfig() requiere que las siguientes dependencias de peer estén instaladas en el proyecto:

npm install -D @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-config-prettier eslint-plugin-prettier

yarn add -D @typescript-eslint/eslint-plugin @typescript-eslint/parser eslint-config-prettier eslint-plugin-prettier

📦 Dependencias internas

Este paquete no tiene dependencias internas del toolkit. Puede utilizarse de forma independiente.

👨‍💻 Uso

ESLint config

Exporta la función eslintConfig() que retorna una configuración ESLint preconfigurada con soporte para TypeScript y Prettier.

// .eslintrc.js
const { eslintConfig } = require('@tresdoce-nestjs-toolkit/commons');
module.exports = eslintConfig();

La configuración resultante incluye:

• Parser: @typescript-eslint/parser con sourceType: 'module'
• Plugins: @typescript-eslint/eslint-plugin
• Extends: plugin:@typescript-eslint/recommended, plugin:prettier/recommended
• Entorno: node: true, jest: true
• Ignore patterns: .eslintrc.js, **/__test__/**/*, dist/, coverage/
• Reglas relajadas: no-explicit-any, no-var-requires, no-require-imports, no-namespace todas en off

Jest config

Exporta la función jestConfig() que retorna una configuración Jest completa con cobertura, reportes y umbrales de calidad.

⚠️ Requisito: jestConfig() espera que exista un archivo jest.setup.ts en el root del proyecto. Sin este archivo, la suite de tests fallará al intentar cargarlo. El archivo puede estar vacío, pero debe existir.

// jest.config.ts
import { jestConfig } from '@tresdoce-nestjs-toolkit/commons';
import type { Config } from 'jest';
import * as dotenv from 'dotenv';

process.env.NODE_ENV = 'test';

dotenv.config({
  path: '.env.test',
});

const config: Config = {
  ...jestConfig(),
  // Descomentar si el proyecto tiene setup/teardown global:
  // globalSetup: './jest.globalSetup.ts',
  // globalTeardown: './jest.globalTeardown.ts',
};

export default config;

Cobertura mínima

Por defecto, jestConfig() exige una cobertura mínima del 80% en branches, functions, lines y statements. Este umbral puede ajustarse con el parámetro minCoveragePercent:

const config: Config = {
  ...jestConfig({ minCoveragePercent: 90 }),
};

El valor de minCoveragePercent está limitado entre minCoverageValue (80) y maxCoverageValue (100). Cualquier valor fuera de ese rango se clampea al límite correspondiente:

import { minCoverageValue, maxCoverageValue } from '@tresdoce-nestjs-toolkit/commons';

console.log(minCoverageValue); // 80
console.log(maxCoverageValue); // 100

jestConfig({ minCoveragePercent: 0 }); // se aplica 80 (mínimo)
jestConfig({ minCoveragePercent: 150 }); // se aplica 100 (máximo)

Características incluidas en la configuración de Jest

• Transform: ts-jest para archivos .ts y .js
• Roots: <rootDir>/test/ y <rootDir>/src/
• Test regex: *.spec.ts, *.it.ts, *.test.ts, *.e2e.ts, *.e2e-spec.ts
• Setup: carga ./jest.setup.ts y jest-extended/all después de cada suite
• Coverage reporters: html, text, text-summary, cobertura, clover, json, lcov
• Reporters: default + jest-junit (con salida compatible con CI)
• Results processor: jest-sonar-reporter (compatible con SonarQube/SonarCloud)
• Display name: toma el valor de npm_package_name del entorno

Webpack config (aplicaciones NestJS estándar)

Para usar la configuración webpack estándar incluida directamente desde nest-cli.json:

// ./nest-cli.json
{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "plugins": ["@nestjs/swagger"],
    "webpack": true,
    "webpackConfigPath": "./node_modules/@tresdoce-nestjs-toolkit/commons/dist-src/build-config/webpack.config.js"
  }
}

Esta configuración:

• Entry: ./src/main.ts
• Target: node
• Externals: webpack-node-externals (excluye node_modules del bundle)
• Modo: development por defecto, production cuando NODE_ENV=build
• Optimización en modo production: minificación con Terser, drop_console: true
• Source maps: habilitados en development, deshabilitados en production

CLI Starter Webpack config

Para proyectos CLI (herramientas de línea de comandos) se provee una configuración webpack especializada que inyecta automáticamente el shebang #!/usr/bin/env node al inicio del archivo de salida:

// ./nest-cli.json
{
  "$schema": "https://json.schemastore.org/nest-cli",
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "webpack": true,
    "webpackConfigPath": "./node_modules/@tresdoce-nestjs-toolkit/commons/dist-src/build-config/cli-starter/webpack.config.js"
  }
}

Esta configuración extiende la webpack estándar y agrega el plugin InjectShebangPlugin. A diferencia de la configuración estándar, en modo production no elimina los console.log (drop_console: false).

InjectShebangPlugin

Plugin de webpack que inyecta una línea shebang al inicio del archivo de salida compilado, necesario para que un script Node.js se ejecute directamente desde la terminal.

import { InjectShebangPlugin } from '@tresdoce-nestjs-toolkit/commons/dist-src/build-config/cli-starter/plugins/inject-shebang.plugin';

// Dentro de webpack.config.js:
plugins: [
  new InjectShebangPlugin({
    filename: 'main.js',          // default: 'main.js'
    shebang: '#!/usr/bin/env node', // default: '#!/usr/bin/env node'
  }),
],

| Opción | Tipo | Default | Descripción | | ---------- | -------- | ----------------------- | ------------------------------------------------------- | | filename | string | 'main.js' | Nombre del archivo de salida al que inyectar el shebang | | shebang | string | '#!/usr/bin/env node' | Línea shebang a inyectar |

El plugin es idempotente: si el shebang ya está presente al inicio del archivo, no lo duplica.

buildConfig

Función para crear una configuración webpack personalizada que se fusiona con la configuración base usando webpack-merge.

// ./webpack.config.js
const { buildConfig } = require('@tresdoce-nestjs-toolkit/commons');

module.exports = (options) => {
  const additionalConfig = {
    entry: './src/serverless.ts', // sobreescribe el entry point por defecto
  };

  return buildConfig(additionalConfig);
};

Deshabilitar la externalización de node_modules

Por defecto, buildConfig excluye los módulos de node_modules del bundle (usando webpack-node-externals). Para proyectos serverless u otros casos donde se necesite incluirlos en el bundle:

module.exports = (options) => {
  return buildConfig({ entry: './src/serverless.ts' }, { externalizeNodeModules: false });
};

Firma

buildConfig(
  additionalConfig?: object,                         // Configuración webpack adicional a fusionar
  options?: { externalizeNodeModules: boolean },     // Default: { externalizeNodeModules: true }
): webpack.Configuration

| Parámetro | Tipo | Default | Descripción | | -------------------------------- | --------- | ------- | ------------------------------------------------------------------------- | | additionalConfig | object | {} | Configuración webpack que se fusiona sobre la base con webpack-merge | | options.externalizeNodeModules | boolean | true | Si es false, incluye node_modules en el bundle (útil para serverless) |

El modo de compilación se determina por NODE_ENV:

• NODE_ENV=build → modo production (minificación habilitada con Terser, drop_console: true)
• Cualquier otro valor → modo development (sin minificación, con source maps)

📖 API Reference

Funciones exportadas

| Función | Módulo | Descripción | | ------------------------------------------ | ----------------- | --------------------------------------------------------------- | | eslintConfig() | eslint-config | Retorna la configuración ESLint base del toolkit | | jestConfig(opts?) | testing-library | Retorna la configuración Jest completa con cobertura y reportes | | buildConfig(additionalConfig?, options?) | build-config | Genera configuración webpack fusionada con la base |

Constantes exportadas

| Constante | Valor | Descripción | | ------------------ | ----- | ------------------------------------ | | minCoverageValue | 80 | Umbral mínimo de cobertura permitido | | maxCoverageValue | 100 | Umbral máximo de cobertura permitido |

Clases exportadas

| Clase | Path | Descripción | | --------------------- | -------------------------------------- | ---------------------------------------------------------------- | | InjectShebangPlugin | build-config/cli-starter/plugins/... | Plugin de webpack que inyecta el shebang en el archivo de salida |

Interfaces internas

| Interfaz | Descripción | | ------------------ | ---------------------------------------------------------------- | | IJestConfigProps | { minCoveragePercent?: number } — parámetros de jestConfig() |

📄 Changelog

Todos los cambios notables de este paquete se documentarán en el archivo Changelog.