Generate NestJS Boilerplate

Description

Table of Contents

• Create new app
• Setup environments
• Start app
• Structure
• Features
  • CQRS
  • Guard
  • Functions
    • Authentication
    • Refresh token (incoming)
    • Manage device login
    • Two authenticator (incoming)
    • CRUD users
    • Reset password
    • Send mail
    • Upload file S3 (incoming)
    • I18n (incoming)
  • Migrations
  • Transformers
  • Exceptions filter
  • Rate limiting
  • Swagger
  • Compodoc
  • Linter
• License

Create new app

• Using npx

npx generate-nest-boilerplate {your-app}

Setup environments

• Install dependencies by running yarn install
• Create .env file by running cp .env.example .env and replace existing env variables

You can create .env.development or .env.staging or .env.production file depend on your environment

• Without using Docker

You have to install Mysql, Redis and replace respective env variables in env file

• Using Docker

yarn db:setup:local

Start app

For development environment

yarn migration:run
yarn start:dev

For production environment

yarn migration:run
yarn start:prod

By default, the app will be run port 8000

Structure

📦{your-app}
 ┣ 📂src
 ┃ ┣ 📂base
 ┃ ┃ ┣ 📂dtos
 ┃ ┃ ┗ 📂entities
 ┃ ┣ 📂common
 ┃ ┃ ┣ 📂constants
 ┃ ┃ ┣ 📂decorators
 ┃ ┃ ┣ 📂dtos
 ┃ ┃ ┣ 📂entities
 ┃ ┃ ┗ 📂exceptions
 ┃ ┣ 📂configs
 ┃ ┃ ┣ 📂app
 ┃ ┃ ┣ 📂database
 ┃ ┃ ┣ 📂queue
 ┃ ┃ ┗ 📜config.module.ts
 ┃ ┣ 📂databases
 ┃ ┃ ┣ 📂factories
 ┃ ┃ ┣ 📂migrations
 ┃ ┃ ┗ 📂seeds
 ┃ ┣ 📂guards
 ┃ ┣ 📂jobs
 ┃ ┣ 📂mail
 ┃ ┣ 📂modules
 ┃ ┃ ┗ 📂{module-name}
 ┃ ┃ ┃ ┣ 📂commands
 ┃ ┃ ┃ ┃ ┣ 📜{command-name}.admin.command.ts
 ┃ ┃ ┃ ┃ ┣ 📜{command-name}.command.ts
 ┃ ┃ ┃ ┃ ┗ 📜{command-name}.local.command.ts
 ┃ ┃ ┃ ┣ 📂controllers
 ┃ ┃ ┃ ┃ ┣ 📜{module-name}.admin.controller.ts
 ┃ ┃ ┃ ┃ ┗ 📜{module-name}.controller.ts
 ┃ ┃ ┃ ┣ 📂dtos
 ┃ ┃ ┃ ┃ ┣ 📜{dto-name}.admin.dto.ts
 ┃ ┃ ┃ ┃ ┣ 📜{dto-name}.dto.ts
 ┃ ┃ ┃ ┃ ┗ 📜{dto-name}.local.dto.ts
 ┃ ┃ ┃ ┣ 📂entities
 ┃ ┃ ┃ ┣ 📂interfaces
 ┃ ┃ ┃ ┣ 📂queries
 ┃ ┃ ┃ ┃ ┣ 📜{command-name}.admin.query.ts
 ┃ ┃ ┃ ┃ ┣ 📜{command-name}.query.ts
 ┃ ┃ ┃ ┃ ┗ 📜{command-name}.local.query.ts
 ┃ ┃ ┃ ┣ 📂repositories
 ┃ ┃ ┃ ┣ 📂services
 ┃ ┃ ┃ ┃ ┣ 📜{module-name}.admin.service.ts
 ┃ ┃ ┃ ┃ ┗ 📜{module-name}.service.ts
 ┃ ┃ ┃ ┗ 📜{module-name}.module.ts
 ┃ ┣ 📂utils
 ┃ ┣ 📂views
 ┃ ┣ 📜app.controller.ts
 ┃ ┣ 📜app.module.ts
 ┃ ┣ 📜app.service.ts
 ┃ ┗ 📜main.ts
 ┣ 📜.env.example
 ┣ 📜docker-compose.yml
 ┣ 📜ormconfig.js
 ┣ 📜package.json
 ┗ 📜tsconfig.json

Naming rules:

• {file-name}.{file-type}.ts: file only for user permission or lower
• {file-name}.admin.{file-type}.ts: file only for admin permission or higher
• {file-name}.local.{file-type}.ts: file only use in logic code, not use in service or controller folder

DTO files is divided into 2 types: input dto and output dto

• Input dto file example: create-user.dto.ts
• Output dto file example: user.dto.ts

Features

CQRS

In most cases, structure model --> repository --> service --> controller is sufficient. However, when our requirements become more complex, the CQRS pattern may be more appropriate and scalable.
You can defined commands and queries in commands and queries folder in each module.

Guard

• Authentication

The boilerplate has been installed passport and jwt.
jwt token is installed in cookies that auto be sent with each request.
It can be enabled by adding JwtAuthGuard to necessary routes in controller files.

@UseGuards(JwtAuthGuard)

The JwtAuthGuard uses combination of Redis and Mysql database to optimize the speed of the app

• Permissions

To enable the permission guard, add PermissionGuard to necessary routes in controller files.

@UseGuards(PermissionGuard)

Some permissions have been installed. Visit file src/common/constants/permission.const.ts to view detail.

Role {
  SUPER_ADMIN = 'super-admin',
  ADMIN = 'admin',
  USER = 'user',
}

User {
  CREATE = 'user:create',
  READ = 'user:read',
  UPDATE = 'user:update',
  DELETE = 'user:delete',
}

• Account status

To enabled this guard, add this code @UseGuards(UserStatusGuard)

User account has 3 status:

• PENDING: User register new account and account has not been activated by email
• ACTIVE: Account has been activated by activation email
• BLOCKED: Account has been blocked by admin

Only ACTIVE account can login to the app.

Functions

• Authentication

  • Login: /auth/login
  • Signup: /auth/signup
  • Logout: /auth/logout

• Refresh token (incoming)

• Manage device login

  API prefix: /auth/devices

  • Get all device information which is logined
  • Get current device infomation
  • Logout all device
  • Logout one device

• Two authenticator (incoming)

• CRUD users

  API prefix: /users and /admin/users

  • CRUD user by admin, super_admin
  • CRUD admin by super_admin

• Reset password

  API prefix: /auth/reset-password

  • By current password
  • By email verification
  • By google authenticator (incoming)

• Send mail

  • Send mail to activate account
  • Send mail to reset password

  Visit src/mail/commands for details

• Upload file S3 (incoming)

• I18n (incoming)

Migrations

• Create migration

Create new migration by running

yarn migration:generate {name-of-migration}

The new migration will be created in src/databases/migrations.

• Run migration

yarn migration:run

• Revert migration

yarn migration:revert

Transformers

• Convert entity to dto to remove unnecessary properties in returned data such as password. The method toDto is installed for each entity. It can be used like that

user.toDto()

• Convert dto to response to format the response that return to client. All the response will be format like that

{
  data: ...
  status: 200,
  message: "Successfully"
}

The method toResponse is installed for each entity. It can be used like that

user.toResponse(HttpStatus.CREATED, 'Create user successfully')

With the response has not return data. You can use method generateEmptyRes

generateEmptyRes(HttpStatus.OK, "Update user successfully");

Exceptions filter

All exceptions will be catched and returned with format

{
  status: 403,
  timestamp: "Sun, 01 Aug 2021 04:35:40 GMT",
  message: "Forbidden resource",
  path:"/users",
}

Rate limiting

Rate limiting is configured by @nestjs/throttler. By default, limit 100 requests per 60s Visit app.module.ts to change this.

Swagger

All APIs are described in Swagger. To see all available endpoints visit http://localhost:8000/api/static/index.html

Compodoc

yarn compodoc

By default, you can see the compodoc on http://localhost:8080

Linter

eslint + prettier = ❤️

License

The MIT License. Please see License File for more information. Copyright © 2021 Tran Duc Minh.

Made with ❤️ by Tran Duc Minh