generate-nest-boilerplate

Generate NestJS Boilerplate

Description

This generator will help you build your own NestJS app in seconds with CQRS, TypeORM, MySQL, Redis, Typescript, Fastify

Create new app

The boilerplate has not supported to install by npm i generate-nest-boilerplate yet.

Using npx

npx generate-nest-boilerplate {your-app}

Table of Contents

• Create new app
  • Using npx
• Setup environments
  • Without using Docker
  • Using Docker
• Start app
• Structure
• Features
  • CQRS
  • Guard
  • Functions
    • Login, signup
    • 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
• License

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
 ┃ ┃ ┃ ┃ ┣ 📜{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

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. 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

Login, signup

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

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

License

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

Made with ❤️ by Tran Duc Minh