Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/innovix-matrix-systems/ims-nest-api-starter

ims-nest-api-starter is a backend API starter template using NestJS, PostgreSQL, Redis, BullMQ and MikroORM designed for scalable applications.
https://github.com/innovix-matrix-systems/ims-nest-api-starter

api-rest bullmq mikro-orm nestjs nestjs-backend nodemailer postgresql redis

Last synced: 3 months ago
JSON representation

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

Awesome Lists containing this project

README 

        


  

    Nest Logo

  




## About this project



`ims-nest-api-starter` is a backend API starter template using [NestJS](https://nestjs.com/), [PostgreSQL](https://www.postgresql.org/), [Redis](https://redis.io/), [BullMQ](https://bullmq.io/), [MikroORM](https://mikro-orm.io/) and [XSECURITY](https://www.npmjs.com/package/nestjs-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](https://nodemailer.com/) with templating support and queue integration.

- **Security Framework**: [XSECURITY](https://www.npmjs.com/package/nestjs-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](https://dbngin.com/)(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`:_



   ```bash

   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:



   ```bash

   openssl rand -base64 64

   ```



   You also need to set up your PostgreSQL(if you prefer other database see this [Database Switch Guide](#database-switch-guide)) user and database:



   ```bash

   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:



   ```bash

   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:



   ```bash

   npm install

   ```



   You can use Husky to manage git hooks:



   ```bash

   npx husky install

   ```



4. **Migrate and Seed the Database:**



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



   ```bash

   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:



   ```bash

   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:



    ```bash

      docker-compose build

    ```



2.  **Start the Application**



    After building the image, start the application using:



    ```bash

      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:



    ```bash

    docker-compose exec app bash

    ```



    Once inside the container, execute the following commands:



    ```bash

    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:



    ```bash

    npx husky install

    ```



## Health Check



To ensure the health of your application, we have integrated [Terminus](https://docs.nestjs.com/recipes/terminus) for health checks.



You can visit `http://localhost:/health` to verify the status.



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



```json

{

  "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](https://mikro-orm.github.io/docs/v3/)



### Steps to Switch to MySQL:



1. **Update Dependencies**

   ```bash

   npm uninstall @mikro-orm/postgresql

   npm install @mikro-orm/mysql

   ```



2. **Update Environment Variables**

   

   In your `.env` file, update the database configuration:

   ```bash

   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:

   ```typescript

   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('DB_NAME', 'your_db_name', this.configService),

         port: Number(getConfigValue('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:

   ```bash

   # 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**

   ```bash

   npm run seeder:run

   ```



## Testing



Run tests using Jest:



```bash

npm run test

```



## Xsecurity Setup



To ensure the security of your application, we have integrated [XSECURITY](https://www.npmjs.com/package/nestjs-xsecurity) which is a security layer that safeguards APIs against unauthorized access by token validation, rate limiting. here is the [XSECURITY Guide](https://github.com/AHS12/nestjs-xsecurity/wiki).



for quick start, you can run the following command:



```bash

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:



```bash

npx mikro-orm schema:generate

```



### Run Migrations:



To manage database schema changes, use:



```bash

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:



```bash

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](https://docs.nestjs.com/cli/overview)



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



```bash

nest generate --help

```



You can create custom CLI commands tailored to your specific needs using the [nestjs-command](https://www.npmjs.com/package/nestjs-command) package.

This project already includes integration with [nestjs-command](https://www.npmjs.com/package/nestjs-command) package.

For reference, check out the `create-module` command implemented in [src/commands/create-module.command.ts](https://github.com/Innovix-Matrix-Systems/ims-nest-api-starter/blob/main/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:



   ```bash

   npm run create:module 

   ```



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



   ```bash

   npm run create:module product

   ```



## Authors



- [@AHS12](https://www.github.com/AHS12)



## Contributors



	

		

            

                

                    AHS12

                    


                    Azizul Hakim

                

            

            

                

                    ajshovon

                    


                    shovon

                

            

            

                

                    amanullah7649

                    


                    MD: AMAN ULLAH

                

            

		

	



## License



This project is brought to you by [Innovix Matrix System](https://innovixmatrixsystem.com/) and is released as open-source software under the [CC0 1.0 License](https://github.com/Innovix-Matrix-Systems/ims-nest-api-starter/blob/main/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!