Amazon web service will be the cloud provider. This is why this project is focused on AWS features.

Http NestJs v9.x boilerplate. Best uses for backend service.

You can request feature or report bug with following this link

• Important
• Next Todo
• Build With
• Objective
• Features
• Structure
  • Folder Structure
  • Module Structure
  • Response Structure
• Prerequisites
• Getting Started
  • Clone Repo
  • Install Dependencies
  • Create environment
  • Database Migration
  • Test
  • Run Project
  • Run Project with Docker
• API Reference
• Environment
• Api Key Encryption
• Adjust Mongoose Setting
• License
• Contact

If you want to implement database transactions, you must run MongoDB as a replication set.

If you change the environment value of APP_ENV to production, that will trigger.

1. CorsMiddleware will implement src/configs/middleware.config.ts.Otherwise is *.
2. Documentation will disable.

Next development

• Implement Repository Design Pattern / Data Access Object Design Pattern
• Swagger for API Documentation
• Mongo Repository soft delete
• Make it simple
• Encrypt jwt payload
• Optimize Unit Testing
• Make serverless separate repo
• Optimize Swagger
• Export to excel and Import from excel add options to background process
• SSO Google
• AuthApi Controller
• Update Documentation, include an diagram for easier comprehension
• OAuth2 Client Credentials
• Maybe will adopt CQRS

Describes which version.

• Easy to maintenance
• NestJs Habit
• Component based folder structure
• Repository Design Pattern or Data Access Layer Design Pattern
• Support Microservice Architecture, Serverless Architecture, Clean Architecture, and/or Hexagonal Architecture
• Follow The Twelve-Factor App
• Adopt SOLID and KISS principle

• NestJs v9.x 🥳
• Typescript 🚀
• Production ready 🔥
• Repository Design Pattern
• Swagger included
• Authentication and authorization (JWT, API Key) 💪
• Role management system
• Storage integration with AwsS3
• Upload file single and multipart to AwsS3
• Support multi-language i18n 🗣
• Request validation with class-validation
• Serialization with class-transformer
• Url Versioning
• Server Side Pagination, there have 3 of types
• Import and export data with excel by using decorator

• MongoDB integrate by using mongoose 🎉
• Multi Database
• Database Transaction
• Database Soft Delete
• Database Migration

• Logger with Morgan
• Debugger with Winston 📝

• Apply helmet, cors, and rate-limit
• Timeout awareness and can override ⌛️
• User agent awareness, and can whitelist user agent

• Support environment file
• Centralize configuration 🤖
• Centralize response
• Centralize exception filter
• Setting from database 🗿
• Maintenance mode on / off from database 🐤

• Support Docker Installation
• Support CI/CD with Github Action or Jenkins
• Husky GitHook For Check Source Code, and Run Test Before Commit 🐶
• Linter with EsLint for Typescript

1. /app The final wrapper module
2. /common The common module
3. /configs The configurations for this project
4. /health health check module for every service integrated
5. /jobs cron job or schedule task
6. /language json languages
7. /migration migrate all init data for test the project
8. /modules other modules based on service/project
9. /router endpoint router. Controller will put in this

Full structure of module

.
└── module1
    ├── abstracts
    ├── constants // constant like enum, static value, status code, etc
    ├── controllers // business logic for rest api
    ├── decorators // warper decorator, custom decorator, etc
    ├── dtos // request validation
    ├── docs // swagger
    ├── errors // custom error
    ├── filters // custom filter 
    ├── guards // validate related with database
    ├── indicators // custom health check indicator
    ├── interceptors // custom interceptors
    ├── interfaces
    ├── pipes
    ├── repository
        ├── entities // database entities
        └── repositories // database repositories
    ├── serializations // response serialization
    ├── services
    ├── tasks // task for cron job
    └── module1.module.ts

This section will describe the structure of the response.

This is useful when we need to give the frontend some information that is not related to the endpoint.

export interface IResponseMetadata {
    languages: ENUM_MESSAGE_LANGUAGE[];
    timestamp: number;
    timezone: string;
    requestId: string;
    path: string;
    version: string;
    repoVersion: string;
    nextPage?: string;
    previousPage?: string;
    firstPage?: string;
    lastPage?: string;
    [key: string]: any;
}

Default response for the response

export interface IResponse {
    metadata?: IResponseMetadata;
    [key: string]: any;
}

Default response for pagination.

export interface IResponsePaging {
    totalData: number;
    totalPage?: number;
    currentPage?: number;
    perPage?: number;
    availableSearch?: string[];
    availableSort?: string[];
    metadata?: IResponseMetadata;
    data: Record<string, any>[];
}

We assume that everyone who comes here is programmer with intermediate knowledge and we also need to understand more before we begin in order to reduce the knowledge gap.

1. Understand NestJs Fundamental, Main Framework. NodeJs Framework with support fully TypeScript.
2. UnderstandTypescript Fundamental, Programming Language. It will help us to write and read the code.
3. Understand ExpressJs Fundamental, NodeJs Base Framework. It will help us in understanding how the NestJs Framework works.
4. Understand what NoSql is and how it works as a database, especially MongoDB.
5. Understand Repository Design Pattern or Data Access Object Design Pattern. It will help to read, and write the source code
6. Understand The SOLID Principle and KISS Principle for better write the code.
7. Optional. Understand Microservice Architecture, Clean Architecture, and/or Hexagonal Architecture. It can help to serve the project.
8. Optional. Understanding The Twelve Factor Apps. It can help to serve the project.
9. Optional. Understanding Docker. It can help to run the project.

Before start, we need to install some packages and tools. The recommended version is the LTS version for every tool and package.

Make sure to check that the tools have been installed successfully.

1. NodeJs
2. MongoDB
3. Yarn
4. Git
5. Docker
6. Docker-Compose

Clone the project with git.

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

This project needs some dependencies. Let's go install it.

yarn install

Make your own environment file with a copy of env.example and adjust values to suit your own environment.

cp .env.example .env

Jump to details

The migration will do data seeding to MongoDB. Make sure to check the value of the DATABASE_ prefix in your.env file.

The Database migration used NestJs-Command

For seeding

yarn seed

For remove all data do

yarn rollback

The test is still not good net. I'm still lazy too do that.

The project provide 3 automation testing unit testing, integration testing, and e2e testing.

yarn test

For specific test do this

• Unit testing

  yarn test:unit

• Integration testing

  yarn test:integration

• E2E testing

  yarn test:e2e

Finally, Cheers 🍻🍻 !!! you passed all steps.

Now you can run the project.

yarn start:dev

docker-compose up -d

We have already provided the API reference. To visit, click here.

Detail information about the environment

Please keep the secret and passphrase private.

ApiKeyHashed uses sha256 encryption, dataObject encryption is AES256.

Here ApiKey data from seeding

{
    "name": "Api Key Migration",
    "description": "From migration",
    "key": "qwertyuiop12345zxcvbnmkjh",
    "secret": "5124512412412asdasdasdasdasdASDASDASD",
    "passphrase": "cuwakimacojulawu",
    "encryptionKey": "opbUwdiS1FBsrDUoPgZdx"
}

To do the encryption.

The encryption process must be on client-side.

1. Make sure to have value of

   • key: You can find the key for apiKey in the database.
   • secret: This value is only generated when the apiKey is created. After that, if you lose the secret, you need to recreate the apiKey.
   • encryptionKey: You can find the key for encryption in the database.
   • passphrase: This is IV for encrypt AES 256. This is need to be private too. Same with secret.

2. Concat the key and secret.

   const concatApiKey = `${key}:${secret}`;

3. Encryption concatApiKey with sha256

   const apiKeyHashed = this.helperHashService.sha256(concatApiKey);

4. Then create dataObject and put the apiKeyHashed into it

   const timestamp: number = this.helperDateService.timestamp();
   const dataObject: IAuthApiRequestHashedData = {
       key, // from 1.key
       timestamp, // ms timestamp
       hash: apiKeyHashed, // from 3
   }

5. Encryption the dataObject with AES 256

   These data encryptionKey, and passphrase can be find in database.

   const passphrase = 'cuwakimacojulawu'; // <--- IV for encrypt AES 256
   const encryptionKey = 'opbUwdiS1FBsrDUoPgZdx';
   const apiKeyEncryption = await authApiService.encryptApiKey(
       data,
       encryptionKey,
       passphrase
   );

6. Last, combine the key and apiKeyEncryption

   const xApiKey = `${key}:${apiEncryption}`;

7. Send into request. Put the xApiKey, timestamp, and passphrase in the request headers

   {
       "headers": {
           "x-api-key": "${xApiKey}", // from 6.xApiKey
           "x-timestamp": "${timestamp}" // from 4.timestamp
           ...
           ...
           ...
       }
   }

Optional, if your mongodb version is < 5

Go to file src/common/database/services/database.options.service.ts and add useMongoClient to mongooseOptions then set value to true.

const mongooseOptions: MongooseModuleOptions = {
    uri,
    useNewUrlParser: true,
    useUnifiedTopology: true,
    serverSelectionTimeoutMS: 5000,
    useMongoClient: true
};

Distributed under MIT licensed.

How to contribute in this repo

1. Fork the project with click Fork button of this repo.

2. Clone the fork project

   git clone "url you just copied"

3. Make necessary changes and commit those changes

4. Commit the changes

   git commit -m "your message"

5. Push changes to fork project

   git push origin -u main

6. Back to browser, goto your fork repo github. Then, click Compare & pull request

If your code behind commit with the original, please update your code and resolve the conflict. Then, repeat from number 6.

• Avoid Circular Dependency
• Consume component folder structure, and repository design pattern
• Always make service for every module is independently.
• Do not put controller into service modules, cause this will break the dependency. Only put the controller into router and then inject the dependency.
• Put the config in /configs folder, and for dynamic config put as environment variable
• CommonModule only for main package, and put the module that related of service/project into /src/modules. So, if we want to clear the unnecessary module, we just need to delete the src/modules/**
• If there a new service in CommonModule. Make sure to create the unit test in /test/unit.
• If there a new controller, make sure to create the e2e testing in test/e2e

Andre Christi kan