About this project

ims-nest-api-starter is a backend API starter template using NestJS, PostgreSQL, Redis, BullMQ, MikroORM and XSECURITY designed for scalable applications.

Key Features

• Authentication: JWT-based token authentication for secure access.
• OAuth Integration: Comprehensive OAuth 2.0 authentication with Google, supporting both backend implementation and frontend token verification.
• Authorization: Role- and permission-based access control to manage user privileges.
• Caching Layer: Redis-powered caching implementation for optimized performance and response times.
• Database Integration: Robust PostgreSQL integration using MikroORM with migration support and relationship management.
• Queue System: Scalable asynchronous processing using BullMQ for background tasks and event handling.
• Email Service: Automated email delivery system utilizing Nodemailer with templating support and queue integration.
• Security Framework: XSECURITY provides Enhanced API protection through XSECURITY middleware, implementing rate limiting, XSS prevention, and request validation. .

Getting Started Guide Without Docker

1. Choose Your Local Development Tool:

   Select your preferred local development tool, such as Dbngin(comes with postgresql and redis) or any other tool that suits your needs.

   Version Requirements

   • Node.js version 18+
   • PostgreSQL 16+
   • Redis 7+

2. Configure Your Environment:

   Update your .env file with the correct database credentials and environment variables.

   Copy .env.example to .env:

   cp .env.example .env

   Configure the following variables:

   • APP_PORT
   • APP_ENV
   • JWT_SECRET
   • JWT_EXPIRATION

   For JWT Secret generation, you can use this command:

   openssl rand -base64 64

   You also need to set up your PostgreSQL(if you prefer other database see this Database Switch Guide) user and database:

   DB_DRIVER=postgres
   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=ims-nest
   DB_USERNAME=postgres
   DB_PASSWORD=

   You can ignore this if you are using Docker (see the Docker section).

   You also need to set up your Redis server:

   REDIS_HOST=localhost
   REDIS_PORT=6379

   You can ignore this if you are using Docker (see the Docker section).

3. Install Dependencies:

   To install all necessary packages, run the following commands:

   npm install

   You can use Husky to manage git hooks:

   npx husky install

4. Migrate and Seed the Database:

   Initialize and seed the database with default data using MikroORM's migration tool:

   npm run migration:up
   npm run seeder:run

   Now, your project is ready for use. You can start exploring the API and customizing your app as needed.

5. Run the Application:

   Start the NestJS server locally:

   npm run start:dev

   The API will run on the port specified in your .env file (APP_PORT).

Getting Started Guide With Docker

1. Build the Docker Image

   To build the Docker image for the application, run the following command:

     docker-compose build

2. Start the Application

   After building the image, start the application using:

     docker-compose up

   the Api should be running at .env.docker file (APP_PORT)(8000) by default.

   You can also use docker-compose up -d to start the application in the background.

   You can also use docker-compose logs -f to follow the logs of the application.

   you can also use docker-compose up --build to build the image and start the application.

3. Run Migrations and Seed Data

   If you need to run database migrations and seed initial data, you can enter the application container with the following command:

   docker-compose exec app bash

   Once inside the container, execute the following commands:

   npm run migration:up
   npm run seeder:run

   This will apply any pending migrations and populate the database with seed data.

4. Git hook for Check You can use Husky to manage git hooks: go to root directory of your project, then run the following command:

   npx husky install

Health Check

To ensure the health of your application, we have integrated Terminus for health checks.

You can visit http://localhost:<APP_PORT>/health to verify the status.

If everything is set up correctly, you should see a response like this:

{
  "status": "ok",
  "info": {
    "ims-nest": {
      "status": "up"
    },
    "database": {
      "status": "up"
    },
    "memory_heap": {
      "status": "up"
    },
    "memory_rss": {
      "status": "up"
    },
    "redis": {
      "status": "up"
    }
  },
  "error": {},
  "details": {
    "ims-nest": {
      "status": "up"
    },
    "database": {
      "status": "up"
    },
    "memory_heap": {
      "status": "up"
    },
    "memory_rss": {
      "status": "up"
    },
    "redis": {
      "status": "up"
    }
  }
}

Database Switch Guide

This guide will show you how to switch databse, for example here we are switching from PostgreSQL to MySQL. MikroORM supported database can be found here: MikroORM docs

Steps to Switch to MySQL:

1. Update Dependencies

   npm uninstall @mikro-orm/postgresql
   npm install @mikro-orm/mysql

2. Update Environment Variables

   In your .env file, update the database configuration:

   DB_DRIVER=mysql
   DB_HOST=localhost
   DB_PORT=3306  # MySQL default port
   DB_NAME=your_database_name
   DB_USERNAME=your_mysql_username
   DB_PASSWORD=your_mysql_password

3. Update MikroORM Configuration

   In your src/config/mikro-orm.config.ts file:

   import { MySqlDriver } from '@mikro-orm/mysql';
   // import { PostgreSqlDriver } from '@mikro-orm/postgresql'; // Remove or comment this
   
   export class MikroOrmConfig {
     configureOptions(): Options {
       return {
         driver: MySqlDriver,
         dbName: getConfigValue<string>('DB_NAME', 'your_db_name', this.configService),
         port: Number(getConfigValue<string>('DB_PORT', '3306', this.configService)),
         // ... other configurations remain the same
       };
     }
   }

4. Reset Migrations

   Since MySQL and PostgreSQL use different SQL syntax, you'll need to recreate your migrations:

   # Remove existing PostgreSQL migrations
   rm -rf ./src/database/migrations/*
   
   # Generate fresh MySQL migrations
   npm run migration:create
   
   # Run the new migrations
   npm run migration:up

5. Run Seeders

   npm run seeder:run

Testing

Run tests using Jest:

npm run test

Xsecurity Setup

To ensure the security of your application, we have integrated XSECURITY which is a security layer that safeguards APIs against unauthorized access by token validation, rate limiting. here is the XSECURITY Guide.

for quick start, you can run the following command:

npx nestjs-xsecurity install

This command will:

• Generate a secure random secret
• Set up required environment variables
• update the existing .env file with the new environment variables

Extra CLI Commands

Generate MikroORM Entities:

Generate entities to help improve your development flow with:

npx mikro-orm schema:generate

Run Migrations:

To manage database schema changes, use:

npm run migration:create
# or
npx mikro-orm migration:create
npm run migration:up
# or
npx mikro-orm migration:up

If you want to drop all migrations and run them again with seed data, use:

npm run migration:fresh
# or
npx mikro-orm migration:fresh --seed

Nest Cli Commands:

You can follow the Nest CLI command to create your required module, service, controller, and others. Visit: Nest CLI Overview

You can also run this command to see all the CLI commands available in your project:

nest generate --help

You can create custom CLI commands tailored to your specific needs using the nestjs-command package. This project already includes integration with nestjs-command package. For reference, check out the create-module command implemented in src/commands/create-module.command.ts.

Custom Module Creation Command

This project includes a custom command to generate a new NestJS module with a well-organized folder structure.

What this command does:

• Creates a new module using the NestJS CLI.
• Generates the associated controller and service.
• Adds additional folders (dto, repositories,) inside the module folder for organizing your code.
• Creates a types.d.ts file for type definitions.

How to Use:

1. Open your terminal and navigate to the project root.

2. Run the following command, replacing yourModuleName with the name of the module you want to create:

   npm run create:module <moduleName>

   For example, to create a module named product, you would run:

   npm run create:module product

Authors

• @AHS12

Contributors

Azizul Hakim

shovon

MD: AMAN ULLAH

License

This project is brought to you by Innovix Matrix System and is released as open-source software under the CC0 1.0 License.

Feel free to use, modify, and distribute this starter project under the CC0 1.0 license terms. Contributions are welcome to improve this template!