NestJS Sandbox API-App

This application is mainly a playground to test technology concerning APIs and TypeScript.
It has no purpose to supply a fully working application but a work-in-progress approach.
Although it has its limitations due to its WIP-nature, it might also be a useful source of inspiration or a staring point for your next app.
To serve as a starting point, the repository is marked as a template.

The applications' branching strategy roughly follows git-flow.
The main development branch is 'develop' and everything finished lives in 'main'. Frozen states will live under versions. It also integrates commitizen for commits and release please changelog and release automation. The application also has a continuous integration setup following along.
The app has two continuous integration pipelines: one for the main branch and one for the development branch. The one for the main branch runs coverage scans and build, as well as changlog and release, whereas the one for the development branch runs the tests, linting and formatting jobs.
A real continuous integration approach would do everything on the main branch and does not apply any specific branching strategy. This would though collide a bit with release please since it would create a new release each time a 'fix' or 'feat' commit is done. That is why the ongoing development is done in a dedicated branch whereas the usable state is in the main branch and the releases.

NestJS and Microservices

This application can be transformed into a microservice application by using the NestJS microservice module. NestJS supports microservices out of the box. The module is called @nestjs/microservices and the documentation can be found here. To transfer this application into a microservice, you need to do the following steps:

• install the microservice module npm install --save @nestjs/microservices
• change the main.ts file to create a microservice instead of a web application. To achieve this, change this line const app: INestApplication = await NestFactory.create(AppModule); to this line const app: INestMicroservice = await NestFactory.createMicroservice(AppModule, { transport: Transport.TCP }); The default transport is TCP, but you can also use other transports like Redis, RabbitMQ or gRPC.
  A good source for health checks in microservices is this example from nestjs/terminus as well as this example for grpc.

Tools used:

• Pipelines:
  • GitHub Actions is used as the default pipeline runner. The repository has two different pipelines, one attached to the dev-branch and one to the main-branch.
    • CI-Dev(: This pipeline runs tests, limiting and formatting. It is triggered by any commit to the 'develop' branch.
    • CI: This pipeline runs an additional dependency check, coverage, build and release steps.
  • CircleCI is a pipeline runner like GitHub actions but with a different way to configure jobs. This is mainly for experimenting with different pipline types and configurations. (freemium tool) To remove or edit the integration, modify or delet the CI config
• Pipeline-Tools:
  • Dependabot is a dependency management tool exclusively for GitHub. The pipeline configuration can be found here. (free tool)
    Important: the labels and milestones mentioned in the configuration need to be present in the respective github project.
  • Release Please is used for release and changelog automation in the CI-Pipeline. It depends on conventional-commits-style of commits. (free tool)
  • CodeCov is a tool to manage code coverage, and make visible, which parts of the code base needs test improvements.
  • SonarCloud is a tool for overall code quality, maintainability and coverage. To remove the integration, delete the file sonar-projects.properties and the step in the ci-pipeline and ci-dev-pipeline.
• Commits:
  • Conventional Commits is used for commits and utilizes commitizen. (free tool)
• Development:
  • NestJS-Devtools is a tool to analyse and debug your local NestJS application (paid tool)
• Environment-Management:
  • dotenv-Vault is a tool to securely distribute your environment configurations across platforms and teams. It is a new way to safely store environment variables. It works with an encrypted .env.vault file that is save to add to version controll and requires an account on dotenv.org. It is recommended though to set up your own account if you want to use your own .env config. See here for more info about the integration into this app. (free tool)
  • As an alternative, you can also change the .env.example file to .env and add your values there. Use this approach if you don't want to use dotenv-vault.
  • To fully use both approaches, the application makes use of dotenv-expand as well.
• Application state:
  • Opentelemetry is a tool to trace and monitor your application (free tool). It also integrates well with tools like Jaeger, Prometheus, Grafana and Sentry. Opentelemetry has tracers for prisma, nestjs, express, http and many more.
  • Jaeger is a tool to trace your application. It is used as a tracing and metrics collector for opentelemetry in development. (free tool)
• Error handling:
  • Sentry is a tool to monitor your application and collect errors. It is used as a tracing collector for opentelemetry in production. (freemium tool)

NestJS integrated tools:

• Read-Eval-Print-Loop(REPL) is a simple interactive environment for dependency graphs and trying out methods from providers and/or controllers from the terminal.

Feature List:

This section contains a list of features, that are implemented and/or planned. As the application has no definite targed so does this list. It will be updated accordingly

• Metrics with Prometheus
  • Collection of default metrics
  • Collection of prisma metrics
  • Middleware for usage data
  • Service methods for different metric types
    • Service method for counter
    • Service method for histogram
    • Service method for gauge
    • Service method for summary
• Healthcheck with Terminus (certain endpoints and database)
  • Healthcheck for root endpoint
  • Healthcheck for certain endpoints
    • Healthcheck for metrics (optional)
    • Healthcheck for OpenAPI
  • Healthcheck for a database
• tracing with opentelemetry
  • jaeger for development (metrics and tracing)
  • prometheus metrics for production
  • sentry
    • for production (error handling and tracing)
    • for development (error handling)
  • tracers
    • http
    • nestjs
    • prisma
    • express
• Database interaction with Prisma
  • Enable prometheus metrics for prisma (usage)
  • Migrations
  • Seeds
  • prisma commands (package.json)
  • prisma query options as a service method
    • paging
  • prisma generators
    • Entity relationship diagram (ERD)
    • NestJS DTOs
• API documentation with OpenAPI
• Unit tests with Jest
• Configuration with NestJS Config
• Configuration schema and validation with Joi

Deployment

• Dockerfile
• Docker-Compose (development)
• Helm Chart

Documentation:

This section lists topics, that have their own file, where they are discussed in detail but in scope of the application.

• dotenv-vault
• Prisma ORM
• Entity Relationship Diagram

License