DEV Community: Javier Batres

NestJS Tips

Javier Batres — Wed, 30 Jun 2021 17:12:56 +0000

NestJS es un framework para backend (inicialmente) que la está empezando a romper y me atrevo a pensar que se volverá estándar poco a poco en la industria. Basado en Express, pero dándole un upgrade importante con TypeScript. Si has programado Angular en sus versiones recientes creo que te será bastante conocido.

State of JS 2020: https://2020.stateofjs.com/es-ES/technologies/back-end-frameworks/

CLI

La CLI o Línea de comandos es una de las cosas que nos hará más simple la vida pues nos permite de forma rápida crear archivos con la estructura necesaria par el correcto funcionamiento con el framework. Es algo que actualmente los frameworks o librerías enfocadas a enterprise ven ya como parte de un mínimo para su distribución. Lo principal es el comando

nest generate / nest g

Con el cual podremos crear diferentes tipos de elementos en nuestro proyecto.

Archivos generables

Nombre	Alias	Descripción
controller	co	Crear un controlador simple en la ruta que le demos
provider	pr	Crear un proveedor o servicio
pipe	pi	Genera el código para un nuevo pipe
gateway	ga	Podemos crear un gateway para el uso de Socket.io
guard	gu	Como en Angular los Guards son para la seguridad y esto nos dará lo básico en el nuevo

Existen muchos más comandos. Si deseas ver la lista completa ingresa a: https://docs.nestjs.com/cli/usages

Configuración

Algo importante al desarrollar software con altos estándares es no "quemar" datos en código tales como la dirección de la base de datos, el usuario, etc. Para esto existen varias prácticas y en este caso lo hacemos a través de un archivo .env.

Para esto lo primero que haremos es instalar un par de dependencias en nuestro proyecto

npm i --save @nestjs/config

Una vez instalada esta dependencia empezaremos creando un archivo .env en la raíz de nuestro proyecto que se verá algo así

PORT=3000
CORS='true'
LOGGER='true'
DB_HOST='xxx.xxx.xxx.xxxx'
DB_PORT='xxxx'
DB_USER='xxxxxxxx'
DB_PASSWORD='xxxxxxxxxxx'
DB_DATABASE='xxxxxxxxx'

Ahora que tenemos este archivo vamos a agregar uno en ./src con el nombre config.ts. La idea de este segundo archivo es convertir esta data del archivo .env en un JSON que sea fácilmente legible en el futuro desde cualquier parte de la aplicación.

export const config = () => ({
  port: Number(process.env.PORT),
  cors: process.env.CORS === 'true',
  logger: process.env.LOGGER === 'true',
  database: {
    type: 'mysql',
    host: process.env.DB_HOST,
    port: Number(process.env.DB_PORT),
    username: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
    database: process.env.DB_DATABASE,
    },
});

Ahora que hemos preparado los recursos necesarios podemos integrar la configuración a nuestro proyecto.

Iremos a nuestro ./src/app.module.ts y en la sección de imports agregaremos el módulo de configuración de la siguiente manera.

...
import { ConfigModule } from '@nestjs/config';
import { config } from './config'
....
@Module({
    imports: [
        ...
        ConfigModule.forRoot({
            isGlobal: true,
            load: [config]
        }),
        ...
    ],Ï
    ...
})
export class AppModule {}

Una vez que agregamos esta instrucción la configuración que es cargada por el ConfigModule es convertida en JSON y puesta a disponibilidad de toda la aplicación.

Sin embargo necesitamos algunos de estos valores antes de iniciar la aplicación en nuestro archivo ./main.ts, por lo que haremos lo siguiente:

import { Logger } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const configService = app.get(ConfigService);
  const cors = configService.get('CORS') === 'true';
  if (cors) {
    app.enableCors();
  }
  const logger = configService.get('LOGGER') === 'true';
  if (logger) {
    app.useLogger(new Logger());
  }
  await app.listen(configService.get('PORT'));
  console.log(`Application is running on: ${await app.getUrl()}`);
}
bootstrap();

En el caso de que utilices TypeORM como yo, te dejo este pequeño truco: Para activar su configuración con este mismo archivo .env. Lo primero que debes hacer es agregar un archivo en el mismo ./src el cual llamaremos database.config.ts y agregaremos lo siguiente:

import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { TypeOrmOptionsFactory } from '@nestjs/typeorm';

@Injectable()
export class DatabaseConfig implements TypeOrmOptionsFactory {
  constructor(private configService: ConfigService) {}

  createTypeOrmOptions() {
    const config = this.configService.get('database');
    return config;
  }
}

De esta manera el archivo tomará el servicio que nos da el ConfigModule y podremos leer la configuración desde el JSON que designamos. Incluso para hacerlo más eficiente vemos que se obtiene solo la sección de database, ya que en este caso es lo único que nos interesa.

Ahora en nuestro archivo de ./src/app.module.ts vamos a modificar nuestra carga del módulo:

...
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { TypeOrmModule } from '@nestjs/typeorm';
import { config } from './config';
import { DatabaseConfig } from './database.config';
....
@Module({
    imports: [
        ...
        ConfigModule.forRoot({
            isGlobal: true,
            load: [config]
        }),
        TypeOrmModule.forRootAsync({
            imports: [ConfigModule],
            useClass: DatabaseConfig
        }),
        ...
    ],Ï
    ...
})
export class AppModule {}  ****

Es importante notar que primero debe cargar el ConfigModule antes del TypeOrmModule.

Logger

En las aplicaciones de servidor es muy importante tener un tracking continuo de las acciones de la misma para que, de ser necesario, encontremos el error o la irregularidad cuanto antes.

Para esto podremos aprovechar el módulo de configuración que vimos anteriormente y agregaremos cosas como los niveles de registros que queremos utilizar sin tener que modificar el código de la aplicación.

Lo primero para esto es agregar una línea a nuestro archivo .env:

...
LOGGER_LEVELS='error,warn,log,verbose,debug'
...

Estos son los 5 niveles que nos dará el framework y los he ordenado según su prioridad, al menos en mi opinión. A continuación agregaremos estos datos a nuestro JSON en ./src/config.ts:

export const config = () => ({
    ...
    loggerLevels: process.env.LOGGER_LEVELS.split(',') || [], 
    ...
});

Ya hemos preparado el terreno, pero continuaremos creando nuestro propio provider el cual podrá ser importado por los otros providers y controllers fácilmente. Para esto usaremos nuestro CLI con el comando:

nest g pr providers/mylogger/mylogger.provider

El cual nos dará un archivo que para cuando terminemos de modificarlo debería verse algo así:

import { Injectable, Logger, Scope } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
@Injectable({ scope: Scope.TRANSIENT })
export class MyLoggerProvider extends Logger {
  levels: string[] = ['error', 'warn', 'log', 'verbose', 'debug'];
  constructor(private config: ConfigService) {
    super();
    this.levels = this.config.get('loggerLevels');
  }

  log(message: string, context?: string) {
    if (this.levels.includes('log')) {
      super.log(message, context);
    }
  }
  error(message: string, trace?: string, context?: string) {
    if (this.levels.includes('error')) {
      super.error(message, trace, context);
    }
  }
  warn(message: string, context?: string) {
    if (this.levels.includes('warn')) {
      super.warn(message, context);
    }
  }
  debug(message: string, context?: string) {
    if (this.levels.includes('debug')) {
      super.debug(message, context);
    }
  }
  verbose(message: string, context?: string) {
    if (this.levels.includes('verbose')) {
      super.verbose(message, context);
    }
  }
}

Como podemos ver lo primero es que hemos cambiado el tipo de Scope para la Inyección del Provider por una transitoria, lo cual permite que cada cliente de este Provider obtenga una instancia independiente. Esto lo queremos así pues nos permitirá manejar el contexto del cliente y saber quien escribió cada registro.

Después observamos que este provider deberá extender de la clase nativa de NestJS Logger la cual nos dará acceso a los métodos de cada tipo de registro.

Finalmente en el constructor de la clase vemos como obtenemos el servicio o provider del ConfigModule con el cual podemos leer la información que nos interesa. Esta información es validada en cada tipo de registro para saber si debe o no ejecutarse la función.

Como último paso iremos a nuestro archivo ./src/main.ts y haremos un pequeño cambio para configurar nuestro nuevo Logger:

import { MyLoggerProvider } from 'providers/mylogger/mylogger.provider';
import { ConfigService } from '@nestjs/config';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
    ...
  if (logger) {
    app.useLogger(new MyLoggerProvider(configService));
  }
    ...
}
bootstrap();

Swagger

Esta es una herramienta que ha ganado mucho uso en la documentación de las aplicaciones de Backend debido a lo simple que es poder visualizar y probar los diferentes endpoints de una API.

En NestJS esto se puede agregar fácilmente con unos pequeños ajustes.

Primero vamos a instalar algunas dependencias.

npm i --save @nestjs/swagger swagger-ui-express

Una vez instalado esto procedemos a nuestro archivo ./main.ts para habilitarlo:

import { MyLoggerProvider } from 'providers/mylogger/mylogger.provider';
import { ConfigService } from '@nestjs/config';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
    ...
  const config = new DocumentBuilder()
      .setTitle('My new API')
      .setDescription('Swagger for my new API')
      .setVersion('1.0')
      .addBearerAuth(
            { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
              'XYZ',
      )
      .build();
      const document = SwaggerModule.createDocument(app, config);
      SwaggerModule.setup('swagger', app, document);
    ...
}
bootstrap();

Esto levantará un servicio de Swagger en /swagger para que puedas probar tus endpoints de una forma amigable. Es importante destacar que por ejemplo, aquí estamos agregando la autenticación de JWT al Swagger para que puedas usar las APIs privadas.

En los controladores que se autentican con JWT, tendremos que agregar un decorador que puede ir en el controlador o bien en cada una de las funciones por lo que se verá algo así:

// Controllers
@ApiBearerAuth('XYZ')
@UseGuards(JwtAuthGuard)
@Controller('settings')

// Funciones
@ApiBearerAuth('XYZ')
@UseGuards(JwtAuthGuard)
@Get()

Documentación

Sé que hacer la documentación de un proyecto es algo que a la mayoría de desarrolladores no nos encanta. Justamente por eso creo que está herramienta es de mis favoritas. En un simple comando tendremos una documentación bastante rigurosa, entendible e incluso interactiva del proyecto gracias al generador compodoc. Para ello solo escribiremos lo siguiente en la raíz de nuestro proyecto.

npx @compodoc/compodoc -p tsconfig.json -s

Esto genera una carpeta documentation en la raíz del proyecto y levanta un servicio HTTP para que podamos verlo en http://localhost:8080 :

Yo sugiero guardar este comando como parte de nuestros scripts en el archivo package.json

Bueno creo que con estos son bastantes tips y herramientas que podemos empezar a integrar en nuestros proyectos con este framework. Si bien tengo algunos más creo que los dejaré para un próximo post.

Priméro quisiera saber que les han parecido los que hemos visto y que me digan si quieren que investigue específicamente alguna funcionalidad.

Typedoc + Angular + Bitbucket

Javier Batres — Mon, 09 Nov 2020 17:56:00 +0000

La verdad es que escribir código es algo increíble. Es de las pocas formas en las que podemos crear algo nuevo e incluso cambiar el mundo desde nuestra silla con una computadora. Ahora bien, con la evolución de la industria cada día necesitamos hacerlo mejor y más rápido. Es allí cuando debemos recurrir a la automatización y conceptos como CI/CD (Continuos Integration / Continuos Deployment) toman peso.

Como resultado de estas necesidades Atlassian ha implementado Pipelines en su producto Bitbucket por lo que reciben el nombre de ¨Bitbucket Pipelines¨ (si, no lo pensaron demasiado).

Como comente en mi artículo anterior (Git Hooks ¿Qué son y para que?), llevo desde marzo 2020 trabajando como freelance para una empresa y pues parte la aventura que empezó como una asesoría, hoy me ha llevado al área de DevOps y a crear estas integraciones para que el equipo de desarrollo funcione de forma más eficiente.

El ejemplo que les explicaré hoy es un proyecto de Angular el cual hemos integrado a Firebase Hosting con nuestro flujo de ramas basado en GitFlow.

Lo primero que explicaré es como creamos nuestra documentación de forma automática mediante Typedoc

Typedoc

Es una librería destinada para proyectos de TypeScript la cual nos permite generar una documentación desde los comentarios del código. Si bien es un poco cansado poner comentarios en nuestro código, la verdad es que cuando la aplicación llega a cierto punto de crecimiento se vuelve una necesidad.

El uso es simple, necesitamos crear un archivo en la raiz de nuestro proyecto que tenga la configuración con la que crearemos nuestra documentación. Algo así:

{
    "out": "docs",
    "tsconfig": "./tsconfig.app.json",
    "theme": "./node_modules/typedoc-bitbucket-theme/dist/",
    "plugin": "typedoc-plugin-markdown",
    "exclude": "**/*+(index|.spec|.e2e).ts",
    "inputFiles": ["./src"]
}

En este caso específicamente estamos usando un tema o plantilla para bitbucket y un plugin que genera los archivos en formato Markdown. De igual manera estamos excluyendo a los test que se crean para los componentes de Angular y estamos setteando la configuración del TypeScript desde nuestro tsconfig.app.json para que reconozca algunos ajustes que hemos hecho. Por último vemos que se coloca una lista con los directorios desde los que leerá los archivos y un dato para el nombre nombre del directorio en el que creara la documentación.

Para ejecutarlo solamente debemos correr el siguiente comando:

npx typedoc

Ambientes

En este escenario trabajamos con 4 ambientes los cuales teníamos que configurar previamente en el proyecto.

Develop
Staging
SandBox
Production

Para el uso de estos despliegues necesitamos un token de Firebase CLI que podremos generar con el comando

firebase login:ci

Tipos de Pipelines

En este caso hemos implementado 2 tipos de pipelines, uno basado en la creación/actualización de los PullRequest y uno en el merge de las ramas. Para esto usamos una rama por ambiente y una rama por cada tarea de desarrollo que se realiza.

Algo importante antes de entrar en estas configuraciones son 2 llaves que usaremos debemos agregar:

$FIREBASE_TOKEN: Token generado con el comando anterior.
$SENTRY_TOKEN: Token de autenticación creado en Sentry.

Por PullRequest

En este caso buscamos utilizar los nuevos canales de pruebas que nos ofrece Firebase Hosting. Por lo que debemos agregar la configuración al archivo bitbucket-pipelins.yml de la siguiente manera:

image: node:12.12.0

pipelines:
  pull-requests:
    "**": #this runs as default for any branch not elsewhere defined
      - step:
          name: PullRequest
          caches:
            - node
          script:
            - npm install --quiet
                         - npm run build:$BITBUCKET_PR_DESTINATION_BRANCH
                         - npx firebase use <project_id>
                         - npx firebase hosting:channel:deploy --token "$FIREBASE_TOKEN" "$BITBUCKET_PR_ID"

Para está configuración vamos a utilizar 2 variables que nos provee de forma automática el ambiente de ¨Bitbucket Pipelines¨ que son:

$BITBUCKET_PR_DESTINATION_BRANCH: Nombre de la rama a la que se quieren unir los cambios.
$BITBUCKET_PR_ID: El Id numérico del PullRequest creado por BitBucket.

Por Merge

Ahora bien en el caso de que un cambio es aprobado y unido al código de la aplicación de forma definitiva, procedemos a realizar una compilación basada en el ambiente que corresponde pero, en está ocasión la diferencia está en las ramas main y develop las cuales realizan algunos pasos extras.

Staging y SandBox

image: node:12.12.0

pipelines:
  branches:
    staging:
      - step:
          name: Deploy to staging
          caches:
            - node
          script:
            - npm install --quiet
            - npm run build:$BITBUCKET_PR_DESTINATION_BRANCH
            - pipe: atlassian/firebase-deploy:0.6.0
              variables:
                FIREBASE_TOKEN: "$FIREBASE_TOKEN"
                PROJECT_ID: "<project_id>"
                MESSAGE: "Deploy to hosting from Pipeline"

Develop

En este caso usamos TypeDoc para generar la documentación y después actualizamos la wiki del repositorio mediante un push de git. Para este proceso necesitamos los siguientes parámetros:

$AUTH_USER: El nombre de usuario que tengamos en BitBucket.
$AUTH_PASSWORD: La contraseña del usuario correspondiente.
$AUTH_NAME: Nombre que el usuario utilizará para realizar el commit.
$AUTH_EMAIL: Correo Electrónico que utiliza el usuario.

image: node:12.12.0

pipelines:
  branches:
    develop:
      - step:
          name: Deploy to Development
          caches:
            - node
          script:
            - npm install --quiet
            - npm run build:develop
            - pipe: atlassian/firebase-deploy:0.6.0
              variables:
                FIREBASE_TOKEN: "$FIREBASE_TOKEN"
                PROJECT_ID: "<project_id>"
                MESSAGE: "Deploy to development from Pipeline"
      - step:
          name: Doc generation
          caches:
            - node
          script:
            - npm install --quiet
            - rm -rf docs/ && npx typedoc
            - rm -rf docs/modules && rm -rf docs/interfaces && rm docs/README.md
            - rm -rf wiki && git clone https://$AUTH_USER:$AUTH_PASSWORD@bitbucket.org/<project>/<repository>.git/wiki
            - cp -r docs/* wiki/.
            - cd wiki && git config user.name "$AUTH_NAME" && git config user.email "$AUTH_EMAIL" && git add * && git commit -m "Updating the wiki autogenerated" && git push origin master
            - cd ..
            - rm -rf wiki && rm -rf docs
            - ls

Main

En este último caso realizamos 3 procesos, el primero es la publicación de la nueva versión del sitio en nuestro hosting con la configuración de producción y después de forma paralela realizamos 2 acciones.

Crear una tag: Esto lo hacemos basados en la versión que obtenemos del archivo package.json del proyecto en cuestión.
Crear un release en Sentry: En nuestro caso utilizamos Sentry, ya que aún no contamos con Firebase Crashlytics para web.

image: node:12.12.0

pipelines:
  branches:
        main:
      - step:
          name: Deploy to Firebase Hosting Prod
          caches:
            - node
          script:
            - npm install --quiet
            - npm run build:prod
            - pipe: atlassian/firebase-deploy:0.6.0
              variables:
                FIREBASE_TOKEN: "$FIREBASE_TOKEN"
                PROJECT_ID: "<project_id>"
                MESSAGE: "Deploy to Prod from Pipeline"
      - parallel:
          - step:
              name: Create Tag
              caches:
                - node
              script:
                - npm install
                - git tag -a $(npx pkg-jq -r .version) -m "Tagged on deployment"
                - git push origin --tags
          - step:
              name: Release on Sentry
              caches:
                - node
              script:
                - pipe: sentryio/sentry-new-release:0.3.0
                  variables:
                    SENTRY_AUTH_TOKEN: $SENTRY_TOKEN
                    SENTRY_ORG: "<sentry_org>"
                    SENTRY_PROJECT: "<sentry_project_id>"

Si deseas saber más de mi puedes visitar mi página: https://fjbatresv.com/