rudemex/nestjs-starter

Starter for BFF, API Rest and microservice with NestJS

NestJS Starter

NestJS es un framework progresivo de Node.js para la creación de aplicaciones eficientes, confiables y escalables del lado del servidor, el cual está construido y es completamente compatible con TypeScript y JavaScript, combinando elementos de la programación orientada a objetos, programación funcional y programación reactiva funcional.

Glosario

• 🥳 Demo
• 🤓 Objetivo
• 📝 Requerimientos básicos
• 🛠️ Instalar dependencias
• ⚙️ Configuración
• 💻 Scripts
• 📚 Swagger
• 🐳 Docker
• 🧰 Toolkit
• 📤 Commits
• 🏷️ Versionado
• 📄 Changelog
• 📜 License MIT

---

🤓 Objetivo

Extensibilidad

Gracias a su arquitectura modular, es flexible y nos permite utilizar las otras bibliotecas existentes en nuestro proyecto.

Arquitectura

Tiene una arquitectura de proyecto que proporciona capacidad de prueba, escalabilidad y mantenimiento sin mucho esfuerzo.

Versatilidad

Proporciona un ecosistema adaptable, el cual está desarrollado para crear todo tipo de aplicaciones del lado del servidor.

Progresividad

Hace uso de las últimas funciones de JavaScript e implementa soluciones maduras y patrones de diseño en el desarrollo de software.

Transaccionalidad

Orquestación de servicios. El BFF es responsable de orquestar la llamada a los distintos servicios y manejarlos transaccionalmente de manera transparente para el cliente.

Performance

Reduce envío de datos. Las API's del BFF se diseñó tomando como base los requerimientos de las pantallas y solo se expondrán los datos que requieran las mismas. Sesión de usuario/caché. Puede manejar caché de sesión para la experiencia del frontend.

Seguridad

Reduce exposición de datos sensibles. El BFF contiene API's que filtran estos datos y solo se exponen los datos necesarios. Gestión de tokens. El BFF es quien se encarga del almacenamiento y gestiona la renovación del access-token.

📝 Requerimientos básicos

• Node.js v18.17.0 or higher (Download)
• YARN v1.22.18 or higher
• NPM v9.6.7 or higher
• NestJS v10.3.0 or higher (Documentación)

🛠️ Instalar dependencias

Cuando tenemos los requisitos básicos, clonamos el repositorio, vamos a la carpeta del proyecto e instalamos sus dependencias.

yarn install

npm install

⚙️ Configuración

Este starter viene con el archivo .env.example y .env.test, el cual contiene las configuraciones básicas para que funcione la aplicación.

Para el entorno de desarrollo local, es necesario contar con un archivo .env del cual se puede utilizar el archivo de ejemplo para generarlo.

# SERVER
APP_STAGE=local
PORT=8080
API_PREFIX=TD_MY_API
CONTEXT=v1
ORIGINS=http://localhost:3000,http://localhost:8080
ALLOWED_HEADERS=Content-Type,Authorization,Set-Cookie,Access-Control-Allow-Origin,Cache-Control,Pragma
ALLOWED_METHODS=GET,HEAD,PUT,POST,DELETE,PATCH,OPTIONS
PROPAGATE_HEADERS=x-custom-header
CORS_ENABLED=true
CORS_CREDENTIALS=false

# SWAGGER ENVIRONMENTS
SWAGGER_PATH=docs
SWAGGER_ENABLED=true

# PARAMS
TEST_KEY="testKeyEnv-dev"

# SERVICES
RICK_AND_MORTY_API_URL=https://rickandmortyapi.com/api

💬 Para ver en detalle todas las propiedades de la configuración, hace click acá.

Server

APP_STAGE: Es el entorno en el que está corriendo la aplicación.

• Type: String
• Default: local
• Values: local | test | snd | dev | qa | homo | prod

PORT: Es el puerto por el cual va a correr el servidor.

• Type: Number
• Default: 8080

API_PREFIX: Es el prefijo que hace referencia a la api, y alimenta otros módulos, como es el de los filter exceptions.

• Type: String
• Default: TD_MY_API

CONTEXT: Es el contexto el que se puede acceder a la API del servidor, de esta manera no se exponen los endpoints en la ruta principal de la aplicación. Se escribe sin el / (slash).

• Type: String
• Default: v1

ORIGINS: Es una whitelist para que la aplicación sólo pueda ser consumida por urls confiables y evitar cualquier tipo de solicitudes no deseadas y maliciosas. Debes escribir las urls separadas por una coma.

• Type: String
• Default: http://localhost:3000,http://localhost:8080

ALLOWED_HEADERS: Parámetros que va a recibir por el header en los request.

• Type: String
• Default: Content-Type,Authorization,Set-Cookie,Access-Control-Allow-Origin,Cache-Control,Pragma

ALLOWED_METHODS: Métodos http disponibles para el cors.

• Type: String
• Default: GET,HEAD,PUT,POST,DELETE,PATCH,OPTIONS

PROPAGATE_HEADERS: Lista de headers que desea propagar en la respuesta del controller.

• Type: String
• Example: x-custom-header,x-custom-header-2,x-custom-header-n

CORS_ENABLED: Habilita o deshabilita el uso de CORS en el servidor.

• Type: Boolean
• Default: false

CORS_CREDENTIALS: Habilita o deshabilita el uso de las credenciales en las peticiones CORS en el servidor.

• Type: Boolean
• Default: false

Swagger

SWAGGER_PATH: Define la ruta de la documentación Swagger, se escribe sin el / (slash).

• Type: String
• Default: docs

SWAGGER_ENABLED: Habilitar o deshabilitar la documentación Swagger de los endpoints del servidor.

• Type: Boolean
• Default: true

Params, Services y Otros environments

A modo de ejemplo, se pueden cargar todas las variables de entorno que requieras, es importante seguir con el esquema de key:value para configurarlas.

# PARAMS
TEST_KEY="testKeyEnv-dev"

# SERVICES
RICK_AND_MORTY_API_URL=https://rickandmortyapi.com/api

Este proyecto utiliza el módulo @nestjs/config, el cual centraliza todas las variables de entorno en un solo lugar y te permite consumirlas como typing para evitar errores de typo, como asi también evitar usar el process.env en todo el proyecto, lo que te permite darle soporte más fácil si se requiere cambiar el KEY de la variable de entorno.

También cuenta con un validador de variables de entorno, que nos permite validar el tipo de dato, si es requerido o no dicha variable, y muchas validaciones más.

Todos estos features los podemos encontrar en la carpeta ./src/config, en dicha carpeta podemos encontrar el archivo environments.ts que es un manejador de env files dependiendo el NODE_ENV que tenga nuestra aplicación.

💻 Scripts

Inicia la aplicación en modo desarrollo

yarn start:dev

npm run start:dev

Inicia los test con coverage

yarn test

npm run test

Realiza el build de la aplicación

yarn build

npm run build

Inicia la aplicación en modo productivo

yarn start

npm run start

Otros scripts

Formatea el código

yarn format

npm run format

Eslintea el código

yarn lint

npm run lint

📚 Swagger

El proyecto cuenta con un Swagger (OpenAPI 3.0.0) que tiene documentado los endpoints con sus definiciones. Demo Swagger

Para expandir la documentación, es importante aplicar los decoradores correspondientes a la aplicación. NestJS OpenApi

Esta documentación puede ser activada o desactivada desde la configuración por medio las variables de entorno del proyecto.

SWAGGER_PATH=docs
SWAGGER_ENABLED=true

URL

Acceso a la documentación y testeo de los endpoints: http://localhost:8080/v1/docs

Scheme

<http|https>://<server_url><:port>/<app-context>/<swagger-path>

Exportar el swagger en JSON

Se puede exportar la documentación a un JSON agregando el sufijo -json al path definido. Demo Swagger JSON

• Default: http://localhost:8080/v1/docs-json
• Schema: <http|https>://<server_url><:port>/<app-context>/<swagger-path>-json

🐳 Docker

El proyecto cuenta con un dockerfile y un docker-compose.yml de base, listo para utilizar y expandir sus capacidades.

Docker Build

Schema: docker build -t <user-docker>/<app-name> .

Schema: docker run -d -p 8080:8080 --name <container-name> --env-file <.env> <user-docker>/<app-name>

Ejemplo

docker build -t nestjs-starter .

docker run -d -p 8080:8080 --name nestjs-starter-app --env-file .env nestjs-starter

📤 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 (más comunes)
• scope: indica la página, componente, funcionalidad
• description: comienza en minúsculas y no debe superar los 72 caracteres.

Ejemplo

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

Breaking change

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

🏷️ Versionado

Este starter cuenta con la posibilidad de auto versionarse por medio del workflow de GitHub Actions (./.github/workflows/release.yml), ya que utiliza la dependencia standard-version y los conventional commits del repositorio. Actualmente, está configurado para incrementar la version en un archivo custom y no en el package.json.

Para poder realizar el versionado correcto en su proyecto, siga estos pasos.

• Asegurarse de que la version del package.json este en un valor inicial (1.0.0), y los datos de la aplicación ajustados.
• Correr el siguiente script para borrar cualquier posible tag local o remoto:

git tag -d $(git tag -l)
git fetch
git push origin --delete $(git tag -l)
git tag -d $(git tag -l)

git fetch
git tag -l | xargs -n 1 git push --delete origin

• Borrar los archivos CHANGELOG.md y version.txt
• Editar el workflow release.yml para que el versionado solo se realice si es una aplicación.

📄 Changelog

All notable changes to this project will be documented in Changelog file.

---

Made with ❤️