A boilerplate for NestJS, using Fastify.
- 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
$ npm install# development
$ npm run start
# watch mode
$ npm run start:dev
# production mode
$ npm run start:prodThe 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.jsonfile in config/ - Creating a
.envfile in the project directory. (supported via dotenv) - Setting environment variables. See the environment variable mappings in custom-environment-variables.json.
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.
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.
Schema changes require migrations.
Migrations can be created using:
npm run migration:makeWhen the server starts, migrations will run automatically, or, you can run the migrations
using npm run migration:latest
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.
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 can either be done using limit and page.
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 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 uploads are enabled.
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.
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.
Private keys are automatically redacted in logged data.
The private keys are specified in redact.ts
{
"username": "mark",
"contact": {
"email": "REDACTED"
}
}A log transport to Grafana Loki is implemented for observability. See OpenTelemetry.
Request context. be accessed using the @ReqCtx() header.
It contains a traceId.
@Get()
function getHello(@ReqCtx() ctx: IReqCtx) {
console.log(ctx.traceId) // 0d8df9931b05fbcd2262bc696a1410a6
}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());A rate limiter is configured
using @nestjs/throttler.
It defaults to 100 request per minute per IP (configurable in default.json)
.
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.
Cleaning response objects using can be enabled using the @Serialize(ClassName) decorator.
It uses class-transformer.
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 support in included with support for traces and metrics.
See the ./observability for a compose file with various services for collecting and viewing signals.
Note: Instrumentation needs to be enabled via config
Logs is not yet supported in the OpenTelemetry SDK, so a log Winston transport to Grafana Loki is present to fill the gap.
Automatic instrumentation is enabled and will suite most needs. Custom spans can be created as described in the OpenTelemetry docs.
const meter = opentelemetry.metrics.getMeter("UserService");
const getUserCounter = this.meter.createCounter("get_user")
getUserCounter.add(1, { user_id: id });The application can be run using docker.
Build
docker build -t nest-boilerplate .
docker run -p 3000:3000 nest-boilerplateDocker Compose can be used to start the application and a database.
docker-compose up -d
There exist unit tests for controllers and services.
Dependencies are mocked using jest.
npm run testA Docker container is created to run end to end tests.
# e2e tests (docker)
npm run test:e2e
# e2e test (locally)
npm run test:e2e:local