Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/rudemex/nestjs-starter
Starter for BFF, API Rest and microservice with NestJS
https://github.com/rudemex/nestjs-starter
api-rest bff nest nestjs nodejs starter swagger
Last synced: 30 days ago
JSON representation
Starter for BFF, API Rest and microservice with NestJS
- Host: GitHub
- URL: https://github.com/rudemex/nestjs-starter
- Owner: rudemex
- License: mit
- Created: 2021-07-29T00:19:15.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2024-11-11T18:16:58.000Z (about 1 month ago)
- Last Synced: 2024-11-11T18:39:19.444Z (about 1 month ago)
- Topics: api-rest, bff, nest, nestjs, nodejs, starter, swagger
- Language: TypeScript
- Homepage: https://nestjs-starter.tresdoce.com.ar/v1/docs/
- Size: 42.9 MB
- Stars: 105
- Watchers: 1
- Forks: 15
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: license.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-nestjs - NestJS Starter - Starter for BFF, MS and API Rest with NestJS, scalable by environments with centralized configuration to use GitOps, CI/CD with GitHub Actions, Dockerization, Conventional commits, versioning, etc... and much more. (Resources)
README
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](https://nestjs-starter.tresdoce.com.ar/v1)
- [🤓 Objetivo](#objective)
- [📝 Requerimientos básicos](#basic-requirements)
- [🛠️ Instalar dependencias](#install-dependencies)
- [⚙️ Configuración](#configurations)
- [💻 Scripts](#scripts)
- [📚 Swagger](#swagger-info)
- [🐳 Docker](#docker)
- [🧰 Toolkit](https://github.com/tresdoce/tresdoce-nestjs-toolkit)
- [📤 Commits](#commits)
- [🏷️ Versionado](#versioning)
- [📄 Changelog](./CHANGELOG.md)
- [📜 License MIT](license.md)
---
## 🤓 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 v20.18.0 or higher ([Download](https://nodejs.org/es/download/))
- YARN v1.22.22 or higher
- NPM v10.9.0 or higher
- NestJS v10.4.7 or higher ([Documentación](https://nestjs.com/))
## 🛠️ 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.
```sh
# 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](https://nestjs-starter.tresdoce.com.ar/v1/docs/)
Para expandir la documentación, es importante aplicar los decoradores correspondientes a la
aplicación. [NestJS OpenApi](https://docs.nestjs.com/openapi/introduction)
Esta documentación puede ser activada o desactivada desde la configuración por medio las variables de entorno del
proyecto.
```sh
SWAGGER_PATH=docs
SWAGGER_ENABLED=true
```
#### URL
Acceso a la documentación y testeo de los endpoints: `http://localhost:8080/v1/docs`
#### Scheme
```
://<:port>//
```
#### Exportar el swagger en JSON
Se puede exportar la documentación a un **JSON** agregando el sufijo **-json** al path
definido. [Demo Swagger JSON](https://nestjs-starter.tresdoce.com.ar/v1/docs-json)
- Default: `http://localhost:8080/v1/docs-json`
- Schema: `://<:port>//-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 / .`
Schema: `docker run -d -p 8080:8080 --name --env-file <.env> /`
### 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`](https://www.conventionalcommits.org/en/v1.0.0/#summary).
```
[optional scope]:
[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](https://github.com/conventional-changelog/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:
```sh
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`](./.github/workflows/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](./CHANGELOG.md) file.
---
Made with ❤️