NodeJS NestJS Starter

Blueprint of a NestJS Service with enterprise features like JSON logging, Swagger UI or Prometheus Metrics included.

Tech

The service...

• is docker'ized
• utilizes Jest and Testcontainers for unit and integration testing
• uses Prisma ORM for database interaction
• provides Prometheus metrics
• provides Swagger UI and OpenAPI Specification
• writes access and application logs in JSON format
• utilizes GitHub Actions for CI/CD
• performs static code analysis via SonarCloud

Run locally

• Native: http://localhost:3000/apidoc

  npm install
  npm run start:dev

• Via Docker: http://localhost:3000/apidoc

  docker compose up --build

API Docs / Swagger UI

Find API docs at /apidoc

Common Actions

• Install dependencies

  npm install

• Start application in dev mode and find API docs at http://localhost:3000/apidoc

  npm run start:dev

• Build docker image and run via docker compose. Find API docs at http://localhost:3000/apidoc

  docker compose up --build

• Run all tests

  npm run test

• Run linting

  npm run lint

• Generate Code Coverage Report. HTML Report can be found in ./coverage/lcov-report/index.html

  npm run test:cov

• Check for outdated dependencies

  npm outdated

How-To

Use logger

import { Logger } from '@nestjs/common';

@Injectable()
export class FooBarService {
  private readonly logger: Logger = new Logger(FooBarService.name);
}

Log errors properly

With NestJS, there are a few possibilities, which deliver a good result:

const e: Error; // either from try/catch or Promise.catch

// log custom error message and error stack
this.logger.error('Something bad happened', e.stack)

// log error object with message, stack, cause etc.
this.logger.error(e)

// log custom error message and error object with message, stack, cause etc.
this.logger.error(e, 'Something bad happened')

Add new configuration property

1. Add default value for the new property to .env.dist, e.g.

   ENV_PROPERTY_XY=42
   

2. Define property validation rules in src/app.config.validation-schema.ts using Joi, e.g.

   export const appConfigValidationSchema = {
     // ...
     ENV_PROPERTY_XY: Joi.number().required().description('Short description of the property'),
     // ...
   };

3. Use the new property within your code

   import { Module } from '@nestjs/common';
   import { ConfigService } from '@nestjs/config';
   
   @Module({
     providers: [ConfigModule]
   })
   export class ExampleModule {
     constructor(private readonly configService: ConfigService) {
       const envPropertyXy: number = Number(this.configService.get<string>('ENV_PROPERTY_XY'));
     }
   }

Change database schema

1. Make your schema changes in /prisma/schema.prisma. See Prisma Docs
2. Make sure you have Prisma installed via running npm install
3. Generate migration scripts in /prisma/migrations/
   1. Start local Postgres via Docker: docker run --name postgres --rm -e POSTGRES_USER=user -e POSTGRES_PASSWORD=pass -e POSTGRES_DB=blueprint -p 5432:5432 -it postgres:alpine
   2. Generate migrations: DATABASE_URL=postgresql://user:pass@localhost:5432/blueprint npx prisma migrate dev
4. Commit the newly generated migration scripts in /prisma/migrations/
5. Update DB on all environments via npx prisma migrate deploy

Make HTTP requests

One option to make HTTP calls is to use the HttpService from the InfrastructureModule:

await httpService
  .fetch(URL)
  .then((response) => {/* handle response */})
  .catch((e) => {/* handle error*/});

OR

try {
  await httpService.fetch(URL);
  /* handle response */
} catch (e) {
  /* handle error*/
}