ACK NestJs Boilerplate 🚀🚀🚀

Boilerplate with Mongoose and MongoDB as Database.
Made with following nodejs-best-practice as benchmark and NestJs Habit.

Explore the docs »

View Source · Report Bug · Request Feature

---

###### IMPORTANT ######

##### LAST UPDATE README ON 18 OCT 2021 ( ONGOING) #####

There huge differences between USAGE.md Documentation and source code after KafkaModule added, Click here to check

---

Description

ACK is a NestJs boilerplate 🚀. ACK uses Typescript Program Language. Best uses for build an API Project, and Microservice Project. Made with following nodejs-best-practice as benchmark and NestJs Habit.

ACK will provide JWT (Json Web Token) Implementation 🔐 (Access Token and Refresh Token), Role and Permission Implementation 👥 , Multi Language Support 🔣 , Database migration, etc. Spill about Features Also provide KafkaModule 🔥, Consumer, and Producer.

Prerequisites

We assume that all people are coming to here is Programmer with intermediate knowledge and also we need to understanding more knowledge before we start to reduce knowledge gaps.

• Understood ExpressJs Fundamental, NodeJs Base Framework. It will help we to understand how the NestJs works.
• Understood Typescript Fundamental, Programming Language. It will help we to write and read the code.
• Understood NestJs Fundamental, NodeJs Framework with support fully TypeScript.
• Understand what is and how NoSql works as a Database, specially MongoDB.

Build With

• NestJs v7.6.11
• Mongoose v5.11.14
• MongoDB v4.4.0
• NodeJs v12.21.0
• Yarn v1.22.10
• Kafka v2.8.0

Features

The features will spill on this section, please read secretly and keep silent 🤫 🤫

• Centralize Configuration
• Centralize Exception
• Centralize Response
• Mongoose Implementation
• Json Web Token Guard
• Basic Auth Guard
• Role and Permission Management.
• Hash Password with Bcrypt
• Database Migration
• Support Multi Language
• Incoming Request Validation
• Logger Module level Database
• Debugger Module level File, on/off feature
• Custom Status Code for Each Error and Success Request

Modules

• AppModule - MainModule
• AuthModule
• AwsModule - S3 Implementation
• ConfigModule
• DatabaseModule
• DebuggerModule
• Helper Module (e.g Manipulation DateTime, Random string or int, etc)
• LoggerModule
• MessageModule - Include LanguageModule
• PaginationModule
• PermissionModule
• PipeModule - RequestValidationPipe
• ResponseModule
• RoleModule
• UserModule
• KafkaModule
  • ProducerModule
  • ConsumerModule
  • AdminModule
• Other Module** (Ongoing)

Welcome to request for other modules

Middleware

• Rate Limit
• Compression
• Helmet
• Cors
• BodyParser

Example

• Simple Test, and Error Test
• Simple CRUD
• Server Side Pagination
• Access Token with JWT
• Refresh Token with JWT
• Basic Auth Implementation
• Login
• Block User, Block Role, and Block Permissions
• Sign Up
• Upload Image into AWS S3
• Kafka Consume and Produce Message
• Mongoose Population and Deep Population

Todo

• Update version NestJs
• Unit Test and E2E Test
• Update Performance ( Code quality and maybe change to fastify)
• Update Documentation

Endpoints

All endpoints in endpoints.json and need import to PostMan. Follow this step for import into Postman

Getting Started

Before we start, we need to install :

• NodeJs (Suggest LTS Version),
• MongoDB (Suggest LTS Version), and
• Optional, Kafka Apache (Suggest LTS Version).

Please see their official document.

For Windows User, do not install kafka on your Windows OS. There are has a unsolved issue, while delete topic on Windows OS. Go install kafka with virtual machine or docker.

Make sure that we don't get any error after installation, open our terminal and follow this instruction

1. Check NodeJs is successful installed in our OS.

   node --version
   
   # will return 
   # v12.21.0

2. Check package manager is running, with yarn

   yarn --version
   
   # will return 
   # 1.22.10

   with npm

   npm --version
   
   # will return 
   # 7.8.0

3. Check MongoDB

   mongod --version
   
   # will return 
   # db version v4.4.0

4. Optional, Kafka

   kafka-topics --version
   
   # will return 
   # 2.8.0 (Commit:ebb1d6e21cc92130

Clone repo, and install all dependencies.

1. Clone

   git clone https://github.com/andrechristikan/ack-nestjs-mongoose

2. Go to into dir

   cd ack-nestjs-mongoose

3. Install dependencies

   yarn

   with npm

   npm i

Setting up the project

1. Build our Env based on .env.example file.

   cp .env.example .env

   and then we need to adjust with our env

   APP_ENV=development
   APP_HOST=localhost
   APP_PORT= 3000
   APP_LANGUAGE=en
   APP_DEBUG=false
   APP_TZ=Asia/Jakarta
   
   DATABASE_HOST=localhost:27017
   DATABASE_NAME=ack
   DATABASE_USER=
   DATABASE_PASSWORD=
   DATABASE_ADMIN=false
   DATABASE_SRV=false
   DATABASE_DEBUG=false
   DATABASE_SSL=false
   DATABASE_OPTIONS=
   
   AUTH_JWT_ACCESS_TOKEN_SECRET_KEY=123456
   AUTH_JWT_ACCESS_TOKEN_EXPIRATION_TIME=1d
   AUTH_JWT_ACCESS_TOKEN_NOT_BEFORE_EXPIRATION_TIME=0
   AUTH_JWT_ACCESS_TOKEN_REMEMBER_ME_EXPIRATION_TIME=7d
   AUTH_JWT_ACCESS_TOKEN_REMEMBER_ME_NOT_BEFORE_EXPIRATION_TIME=0
   
   AUTH_JWT_REFRESH_TOKEN_SECRET_KEY=01001231
   AUTH_JWT_REFRESH_TOKEN_EXPIRATION_TIME=2d
   AUTH_JWT_REFRESH_TOKEN_NOT_BEFORE_EXPIRATION_TIME=1d
   AUTH_JWT_REFRESH_TOKEN_REMEMBER_ME_EXPIRATION_TIME=9d
   AUTH_JWT_REFRESH_TOKEN_REMEMBER_ME_NOT_BEFORE_EXPIRATION_TIME=7d
   
   AUTH_BASIC_TOKEN_CLIENT_ID=asdzxc
   AUTH_BASIC_TOKEN_CLIENT_SECRET=1234567890
   
   HELPER_IMAGE_MAX_SIZE=1048576
   
   KAFKA_CONSUMER_GROUP=nestjs.ack
   KAFKA_BROKERS=localhost:9092
   
   AWS_CREDENTIAL_KEY=awskey12345
   AWS_CREDENTIAL_SECRET=awssecret12345
   AWS_S3_REGION=us-east-2
   AWS_S3_BUCKET=acks3

2. Create Database, follow this instruction from mongodb official

3. We need to Migration Role and Permission for first usage

   • Fresh migrate

     yarn migrate

     with npm

     npm run migrate

   • Rollback migrate

     yarn migrate:rollback

     with npm

     npm run migrate:rollback

4. *** PLEASE SKIP THIS STEP, UNIT TEST, AND E2E TEST DO NOT FINISH YET *** .

   Make sure we do the correct step. Go run TestModule and make sure all test passed with success status.

   • Run Unit Testing

     yarn test

     with npm

     npm run test

   • Run E2E Testing

     yarn test:e2e

     with npm

     npm run test:e2e

5. Optional, if we want to use Kafka we need to adjustment some point. In src/main.ts, Add This Code.

   // src/main.ts
   
   ...
   ...
   
   await app.listenAsync(port, host);
   
   const kafka = await import('./kafka');
   await kafka.default(
       app,
       configService,
       logger
   );
   
   ...
   ...

   In src/app/app.module.ts, Import add KafkaAdminModule, KafkaProducerModule, KafkaConsumerModule.

   // src/app/app.module.ts
   import { KafkaAdminModule } from 'src/kafka/admin/kafka.admin.module';
   import { KafkaProducerModule } from 'src/kafka/producer/producer.module';
   import { KafkaConsumerModule } from 'src/kafka/consumer/consumer.module';
   
   @Module({
     controllers: [AppController],
     providers: [],
     imports: [
       ...
       ...
   
       SeedsModule,
       KafkaAdminModule, // <<<---- Optional, add this if we want to create custom partition and partition replication
       KafkaProducerModule, // <<<---- Add this
       KafkaConsumerModule, // <<<---- Add this
   
       AuthModule,
       UserModule,
   
       ...
       ...
     ]
   })
   export class AppModule {}

   We can test KafkaProducerModule and KafkaConsumerModule with manual hit /kafka/produce endpoint.

   Note: If we won't use kafka, simply we can delete kafka folder and remove config in config/kafka.config.ts

6. Last step, run the project

   yarn start:dev

   with npm

   npm run start:dev

Congrats !!! Cheers 🍻🍻, our project is running well. Now we can use all features.

Go install or open REST Client you prefer. In this case, let assume we use Postman Client. After installation, we need to import all endpoint into postman, see this instruction.

Usage

Documents usage will has difference file. Document will put in USAGE.md

License

Distributed under MIT licensed.

Contact

Andre Christi kan

back to top