marknjunge / nest-boilerplate

A boilerplate for NestJS with support for database, swagger, config, rate limiting, logging, validation, exception handling, docker, testing and CI.

Nest Starter

A boilerplate for NestJS, using Fastify.

Features

• Config
• Database
• Swagger (API docs)
• Query Parsing
• File Upload
• Logging
• Request Context
• Auth guard
• Rate limiting
• Request body validation
• Exception Handling
• OpenTelemetry
• Docker
• Testing
• Continuous Integration

Installation

$ npm install

Running

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod

Config

The node-config package to manage configs.

Default config values are found in default.json.
These values can be overridden by:

• Creating config files as described in node-config docs
• Creating a local.json file in config/
• Creating a .env file in the project directory. (supported via dotenv)
• Setting environment variables. See the environment variable mappings in custom-environment-variables.json.

CORS

CORS is configurable via the config.

The following values are acceptable for config.cors.origins:

• * - Will accept any origin.
• https://example.com,https://example2.com - Will accept all domains in the comma separated list.

Note: The access-control-allow-origin header will always respond with the origin in the request, even if * is used.

Database

Objection (which uses Knex.js) is used for database operations.

It uses PostgreSQL by default, but that can be changed by changing the client in knexfile.ts.
See Knex documentation for supported databases.

Conversion of column names from camel case to snake case is automatically done in most cases.
It however does not work in all cases. See excerpt below from Objection docs (Snake case to camel case conversion):

When the conversion is done on objection level only database columns of the returned rows (model instances) are convered to camel case. You still need to use snake case in relationMappings and queries. Note that insert, patch, update and their variants still take objects in camel case. The reasoning is that objects passed to those methods usually come from the client that also uses camel case.

Migrations

Schema changes require migrations.

Migrations can be created using:

npm run migration:make

When the server starts, migrations will run automatically, or, you can run the migrations using npm run migration:latest

Swagger

Swagger documentation is automatically generated from the routes.

By default it is available at http://127.0.0.1:3000/docs

See config in default.json.

Query Parsing

URL query to DB query parsing is available. See query-parser.ts.

Note: There is currently no limitation put on the complexity of the query, so this should be exposed with caution.

Example:

limit=10&page=1&orderBy=(averageRating,DESC)&filter=(authors,=,Bill Bryson):(yearPublished,>,2000)

SELECT "*"
FROM   "..."
WHERE  "authors" = 'Bill Bryson'
  AND "year_published" > '2000'
ORDER  BY "average_rating" DESC
  LIMIT  10 

Paging

Paging can either be done using limit and page.

Filters

Filters take the format of (column,operand,value) where the operand can be =,>,>=,<,<=.
Column names are automatically converted to snake case.
Multiple filters can be specified using a colon : as the delimiter.

Ordering

Ordering takes the format of (column,direction) where direction can be desc,DESC,asc,ASC.
Multiple orderings can be specified using a colon : as the delimiter.

File Upload

File uploads are enabled.

Config

maxSize: number - Max size in bytes. Default 5MB.
uploadDir: string - Upload directory. If blank, it will default to the OS's temp directory.
removeAfterUpload: string - Whether to delete files after the request completes.

Upload a single file

@ApiProperty({ type: "string", format: "binary" })
@IsNotEmpty()
@IsObject({ message: "$property must be a single file" })
@ValidateNested({ message: "$property must be a file" })
@Type(() => UploadedFileDto)
file2: UploadedFileDto;

Upload multiple files

@ApiProperty({ type: "array", items: { type: "string", format: "binary" } })
@IsNotEmpty()
@IsArray({ message: "$property must be multiple files" })
@ValidateNested({ message: "$property must be a file", each: true })
@Type(() => UploadedFileDto)
file1: UploadedFileDto[];

See FileUploadDto for a full example.

Logging

A custom logger is implemented using winston.

Create a logger instance using new CustomLogger().
A parameter can be passed into the constructor and to be used as a tag (defaults to "Application").

For example,

const logger = new CustomLogger("AppService");

this.logger.debug("Hello!");

// Output:
// 2019-05-10 19:47:21.570 | debug: [AppService] Hello!

A custom tag can be passed into the log functions.

this.logger.debug("Hello!", { tag: "AppService.getHello" });

// Output
// 2019-05-10 19:54:43.062 | debug: [AppService.getHello] Hello!

Extra data can be passed into the log functions. To enable printing it to the console, set the config logging.logDataConsole to true.

this.logger.debug("Hello!", "AppService.getHello", { data: { user: "mark" } });

// Output
// 2022-07-10 11:59:43.319 | debug: [AppService] Hello!
// {"user":"mark"}

To log to other locations, a custom transport is needed. See SampleTransport for an example.

Redact Private Keys

Private keys are automatically redacted in logged data.

The private keys are specified in redact.ts

{
  "username": "mark",
  "contact": {
    "email": "REDACTED"
  }
}

Grafana Loki

A log transport to Grafana Loki is implemented for observability. See OpenTelemetry.

Request Context

Request context. be accessed using the @ReqCtx() header.

It contains a traceId.

@Get()
function getHello(@ReqCtx() ctx: IReqCtx) {
  console.log(ctx.traceId) // 0d8df9931b05fbcd2262bc696a1410a6
}

Auth Guard

An authentication guard is available in auth.guard.ts

It can be enabled by adding a UseGuards decorator to a controller or route

@UseGuards(AuthGuard)

or globally

app.useGlobalGuards(new AuthGuard());

Rate Limiting

A rate limiter is configured using @nestjs/throttler.
It defaults to 100 request per minute per IP (configurable in default.json) .

Request Body Validation

class-validator and class-transformer are used to validate request bodies.

See class-validator decorators for available validation options.

An example of a response to an invalid body:

{
  "status": 400,
  "message": "Validation errors with properties [name,username,contact.mail,contact.email]",
  "code": "ValidationError",
  "meta": [
    {
      "property": "name",
      "constraints": [
        "property name should not exist"
      ]
    },
    {
      "property": "username",
      "constraints": [
        "username should not be empty"
      ]
    },
    {
      "property": "contact.mail",
      "constraints": [
        "property mail should not exist"
      ]
    },
    {
      "property": "contact.email",
      "constraints": [
        "email should not be empty"
      ]
    }
  ]
}

NB: Raising an error when unknown values are passed can be disabled by setting validator.forbidUnknown to false in the config.

Response Mapping

Cleaning response objects using can be enabled using the @Serialize(ClassName) decorator. It uses class-transformer.

Errors & Exception Handling

Exceptions should be thrown using the custom HttpException class.

throw new HttpException(404, `User ${1} was not found`, ErrorCodes.INVALID_USER, { id: 1 });

{
  "status": 404,
  "message": "User 1 was not found",
  "code": "InvalidUser",
  "traceId": "775523bae019485d",
  "meta": {
    "id": 1
  }
}

Regular errors an unhandled exceptions are also caught and returned as a 500 response.

{
  "status": 500,
  "message": "Uncaught exception",
  "code": "InternalError",
  "traceId": "d3cb1b2b3388e3b1"
}

OpenTelemetry

OpenTelemetry support in included with support for traces and metrics.

See instrumentation.ts for config.

See Observability directory for a compose file with various services for collecting and viewing signals.

Logs is not yet supported in the SDK, so a log transport to Grafana Loki is present to fill the gap.

Traces

Automatic instrumentation is enabled and will suite most needs. Custom spans can be created as described in the OpenTelemetry docs.

Metrics

See OpenTelemetry docs

const meter = opentelemetry.metrics.getMeter("UserService");
const getUserCounter = this.meter.createCounter("get_user")
getUserCounter.add(1, { user_id: id });

Docker

The application can be run using docker.

Build

docker build -t nest-boilerplate .

docker run -p 3000:3000 nest-boilerplate

Docker Compose can be used to start the application and a database.

docker-compose up -d

Testing

Unit test

There exist unit tests for controllers and services.

Dependencies are mocked using jest.

npm run test

End-to-end test

A Docker container is created to run end to end tests.

See docker-compose-e2e.yml

# e2e tests (docker)
npm run test:e2e

# e2e test (locally)
npm run test:e2e:local

CI

Github Actions config