{"id":17931027,"url":"https://github.com/innovix-matrix-systems/ims-nest-api-starter","last_synced_at":"2025-03-24T04:31:34.940Z","repository":{"id":259186034,"uuid":"871359677","full_name":"Innovix-Matrix-Systems/ims-nest-api-starter","owner":"Innovix-Matrix-Systems","description":"ims-nest-api-starter is a backend API starter template using NestJS, PostgreSQL, Redis, BullMQ and MikroORM designed for scalable applications.","archived":false,"fork":false,"pushed_at":"2024-12-22T05:07:17.000Z","size":601,"stargazers_count":31,"open_issues_count":0,"forks_count":9,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-19T02:11:25.305Z","etag":null,"topics":["api-rest","bullmq","mikro-orm","nestjs","nestjs-backend","nodemailer","postgresql","redis"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Innovix-Matrix-Systems.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-11T19:50:33.000Z","updated_at":"2025-03-04T14:05:43.000Z","dependencies_parsed_at":"2024-10-23T10:32:37.195Z","dependency_job_id":"21c18ad7-c8b4-4b26-9cf6-4242c7039002","html_url":"https://github.com/Innovix-Matrix-Systems/ims-nest-api-starter","commit_stats":null,"previous_names":["innovix-matrix-systems/ims-nest-api-starter"],"tags_count":4,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Innovix-Matrix-Systems%2Fims-nest-api-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Innovix-Matrix-Systems%2Fims-nest-api-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Innovix-Matrix-Systems%2Fims-nest-api-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Innovix-Matrix-Systems%2Fims-nest-api-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Innovix-Matrix-Systems","download_url":"https://codeload.github.com/Innovix-Matrix-Systems/ims-nest-api-starter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245211234,"owners_count":20578375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-rest","bullmq","mikro-orm","nestjs","nestjs-backend","nodemailer","postgresql","redis"],"created_at":"2024-10-28T21:19:07.487Z","updated_at":"2025-03-24T04:31:34.931Z","avatar_url":"https://github.com/Innovix-Matrix-Systems.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\r\n  \u003ca href=\"http://nestjs.com/\" target=\"blank\"\u003e\r\n    \u003cimg src=\"https://nestjs.com/img/logo-small.svg\" width=\"120\" alt=\"Nest Logo\" /\u003e\r\n  \u003c/a\u003e\r\n\u003c/p\u003e\r\n\r\n## About this project\r\n\r\n`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.\r\n\r\n### Key Features\r\n\r\n- **Authentication**: JWT-based token authentication for secure access.\r\n- **OAuth Integration**: Comprehensive OAuth 2.0 authentication with Google, supporting both backend implementation and frontend token verification.\r\n- **Authorization**: Role- and permission-based access control to manage user privileges.\r\n- **Caching Layer**: Redis-powered caching implementation for optimized performance and response times.\r\n- **Database Integration**: Robust PostgreSQL integration using MikroORM with migration support and relationship management.\r\n-  **Queue System**: Scalable asynchronous processing using BullMQ for background tasks and event handling.\r\n- **Email Service**: Automated email delivery system utilizing [Nodemailer](https://nodemailer.com/) with templating support and queue integration.\r\n- **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.\r\n.\r\n\r\n## Getting Started Guide Without Docker\r\n\r\n1. **Choose Your Local Development Tool:**\r\n\r\n   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.\r\n\r\n   ### Version Requirements\r\n\r\n   - Node.js version 18+\r\n   - PostgreSQL 16+\r\n   - Redis 7+\r\n\r\n2. **Configure Your Environment:**\r\n\r\n   Update your `.env` file with the correct database credentials and environment variables.\r\n\r\n   _Copy `.env.example` to `.env`:_\r\n\r\n   ```bash\r\n   cp .env.example .env\r\n   ```\r\n\r\n   Configure the following variables:\r\n\r\n   - `APP_PORT`\r\n   - `APP_ENV`\r\n   - `JWT_SECRET`\r\n   - `JWT_EXPIRATION`\r\n\r\n   For JWT Secret generation, you can use this command:\r\n\r\n   ```bash\r\n   openssl rand -base64 64\r\n   ```\r\n\r\n   You also need to set up your PostgreSQL(if you prefer other database see this [Database Switch Guide](#database-switch-guide)) user and database:\r\n\r\n   ```bash\r\n   DB_DRIVER=postgres\r\n   DB_HOST=localhost\r\n   DB_PORT=5432\r\n   DB_NAME=ims-nest\r\n   DB_USERNAME=postgres\r\n   DB_PASSWORD=\r\n   ```\r\n\r\n   You can ignore this if you are using Docker (see the Docker section).\r\n\r\n   You also need to set up your Redis server:\r\n\r\n   ```bash\r\n   REDIS_HOST=localhost\r\n   REDIS_PORT=6379\r\n   ```\r\n\r\n   You can ignore this if you are using Docker (see the Docker section).\r\n\r\n3. **Install Dependencies:**\r\n\r\n   To install all necessary packages, run the following commands:\r\n\r\n   ```bash\r\n   npm install\r\n   ```\r\n\r\n   You can use Husky to manage git hooks:\r\n\r\n   ```bash\r\n   npx husky install\r\n   ```\r\n\r\n4. **Migrate and Seed the Database:**\r\n\r\n   Initialize and seed the database with default data using MikroORM's migration tool:\r\n\r\n   ```bash\r\n   npm run migration:up\r\n   npm run seeder:run\r\n   ```\r\n\r\n   Now, your project is ready for use. You can start exploring the API and customizing your app as needed.\r\n\r\n5. **Run the Application:**\r\n\r\n   Start the NestJS server locally:\r\n\r\n   ```bash\r\n   npm run start:dev\r\n   ```\r\n\r\n   The API will run on the port specified in your `.env` file (`APP_PORT`).\r\n\r\n## Getting Started Guide With Docker\r\n\r\n1.  **Build the Docker Image**\r\n\r\n    To build the Docker image for the application, run the following command:\r\n\r\n    ```bash\r\n      docker-compose build\r\n    ```\r\n\r\n2.  **Start the Application**\r\n\r\n    After building the image, start the application using:\r\n\r\n    ```bash\r\n      docker-compose up\r\n    ```\r\n\r\n    the Api should be running at `.env.docker` file (`APP_PORT`)(8000) by default.\r\n\r\n    You can also use `docker-compose up -d` to start the application in the background.\r\n\r\n    You can also use `docker-compose logs -f` to follow the logs of the application.\r\n\r\n    you can also use `docker-compose up --build` to build the image and start the application.\r\n\r\n3.  **Run Migrations and Seed Data**\r\n\r\n    If you need to run database migrations and seed initial data, you can enter the application container with the following command:\r\n\r\n    ```bash\r\n    docker-compose exec app bash\r\n    ```\r\n\r\n    Once inside the container, execute the following commands:\r\n\r\n    ```bash\r\n    npm run migration:up\r\n    npm run seeder:run\r\n    ```\r\n\r\n    This will apply any pending migrations and populate the database with seed data.\r\n\r\n4.  **Git hook for Check**\r\n    You can use Husky to manage git hooks:\r\n    go to root directory of your project, then run the following command:\r\n\r\n    ```bash\r\n    npx husky install\r\n    ```\r\n\r\n## Health Check\r\n\r\nTo ensure the health of your application, we have integrated [Terminus](https://docs.nestjs.com/recipes/terminus) for health checks.\r\n\r\nYou can visit `http://localhost:\u003cAPP_PORT\u003e/health` to verify the status.\r\n\r\nIf everything is set up correctly, you should see a response like this:\r\n\r\n```json\r\n{\r\n  \"status\": \"ok\",\r\n  \"info\": {\r\n    \"ims-nest\": {\r\n      \"status\": \"up\"\r\n    },\r\n    \"database\": {\r\n      \"status\": \"up\"\r\n    },\r\n    \"memory_heap\": {\r\n      \"status\": \"up\"\r\n    },\r\n    \"memory_rss\": {\r\n      \"status\": \"up\"\r\n    },\r\n    \"redis\": {\r\n      \"status\": \"up\"\r\n    }\r\n  },\r\n  \"error\": {},\r\n  \"details\": {\r\n    \"ims-nest\": {\r\n      \"status\": \"up\"\r\n    },\r\n    \"database\": {\r\n      \"status\": \"up\"\r\n    },\r\n    \"memory_heap\": {\r\n      \"status\": \"up\"\r\n    },\r\n    \"memory_rss\": {\r\n      \"status\": \"up\"\r\n    },\r\n    \"redis\": {\r\n      \"status\": \"up\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## Database Switch Guide\r\n\r\nThis guide will show you how to switch databse, for example here we are switching from PostgreSQL to MySQL.\r\nMikroORM supported database can be found here: [MikroORM docs](https://mikro-orm.github.io/docs/v3/)\r\n\r\n### Steps to Switch to MySQL:\r\n\r\n1. **Update Dependencies**\r\n   ```bash\r\n   npm uninstall @mikro-orm/postgresql\r\n   npm install @mikro-orm/mysql\r\n   ```\r\n\r\n2. **Update Environment Variables**\r\n   \r\n   In your `.env` file, update the database configuration:\r\n   ```bash\r\n   DB_DRIVER=mysql\r\n   DB_HOST=localhost\r\n   DB_PORT=3306  # MySQL default port\r\n   DB_NAME=your_database_name\r\n   DB_USERNAME=your_mysql_username\r\n   DB_PASSWORD=your_mysql_password\r\n   ```\r\n\r\n3. **Update MikroORM Configuration**\r\n   \r\n   In your `src/config/mikro-orm.config.ts` file:\r\n   ```typescript\r\n   import { MySqlDriver } from '@mikro-orm/mysql';\r\n   // import { PostgreSqlDriver } from '@mikro-orm/postgresql'; // Remove or comment this\r\n\r\n   export class MikroOrmConfig {\r\n     configureOptions(): Options {\r\n       return {\r\n         driver: MySqlDriver,\r\n         dbName: getConfigValue\u003cstring\u003e('DB_NAME', 'your_db_name', this.configService),\r\n         port: Number(getConfigValue\u003cstring\u003e('DB_PORT', '3306', this.configService)),\r\n         // ... other configurations remain the same\r\n       };\r\n     }\r\n   }\r\n   ```\r\n\r\n4. **Reset Migrations**\r\n   \r\n   Since MySQL and PostgreSQL use different SQL syntax, you'll need to recreate your migrations:\r\n   ```bash\r\n   # Remove existing PostgreSQL migrations\r\n   rm -rf ./src/database/migrations/*\r\n   \r\n   # Generate fresh MySQL migrations\r\n   npm run migration:create\r\n   \r\n   # Run the new migrations\r\n   npm run migration:up\r\n   ```\r\n\r\n5. **Run Seeders**\r\n   ```bash\r\n   npm run seeder:run\r\n   ```\r\n\r\n## Testing\r\n\r\nRun tests using Jest:\r\n\r\n```bash\r\nnpm run test\r\n```\r\n\r\n## Xsecurity Setup\r\n\r\nTo 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).\r\n\r\nfor quick start, you can run the following command:\r\n\r\n```bash\r\nnpx nestjs-xsecurity install\r\n```\r\nThis command will:\r\n- Generate a secure random secret\r\n- Set up required environment variables\r\n- update the existing `.env` file with the new environment variables\r\n\r\n## Extra CLI Commands\r\n\r\n### Generate MikroORM Entities:\r\n\r\nGenerate entities to help improve your development flow with:\r\n\r\n```bash\r\nnpx mikro-orm schema:generate\r\n```\r\n\r\n### Run Migrations:\r\n\r\nTo manage database schema changes, use:\r\n\r\n```bash\r\nnpm run migration:create\r\n# or\r\nnpx mikro-orm migration:create\r\nnpm run migration:up\r\n# or\r\nnpx mikro-orm migration:up\r\n```\r\n\r\nIf you want to drop all migrations and run them again with seed data, use:\r\n\r\n```bash\r\nnpm run migration:fresh\r\n# or\r\nnpx mikro-orm migration:fresh --seed\r\n```\r\n\r\n### Nest Cli Commands:\r\n\r\nYou 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)\r\n\r\nYou can also run this command to see all the CLI commands available in your project:\r\n\r\n```bash\r\nnest generate --help\r\n```\r\n\r\nYou can create custom CLI commands tailored to your specific needs using the [nestjs-command](https://www.npmjs.com/package/nestjs-command) package.\r\nThis project already includes integration with [nestjs-command](https://www.npmjs.com/package/nestjs-command) package.\r\nFor 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).\r\n\r\n### Custom Module Creation Command\r\n\r\nThis project includes a custom command to generate a new NestJS module with a well-organized folder structure.\r\n\r\n### What this command does:\r\n\r\n- Creates a new module using the NestJS CLI.\r\n- Generates the associated controller and service.\r\n- Adds additional folders (`dto`, `repositories`,) inside the module folder for organizing your code.\r\n- Creates a `types.d.ts` file for type definitions.\r\n\r\n### How to Use:\r\n\r\n1. Open your terminal and navigate to the project root.\r\n2. Run the following command, replacing `yourModuleName` with the name of the module you want to create:\r\n\r\n   ```bash\r\n   npm run create:module \u003cmoduleName\u003e\r\n   ```\r\n\r\n   For example, to create a module named `product`, you would run:\r\n\r\n   ```bash\r\n   npm run create:module product\r\n   ```\r\n\r\n## Authors\r\n\r\n- [@AHS12](https://www.github.com/AHS12)\r\n\r\n## Contributors\r\n\r\n\u003c!-- readme: contributors -start --\u003e\r\n\u003ctable\u003e\r\n\t\u003ctbody\u003e\r\n\t\t\u003ctr\u003e\r\n            \u003ctd align=\"center\"\u003e\r\n                \u003ca href=\"https://github.com/AHS12\"\u003e\r\n                    \u003cimg src=\"https://avatars.githubusercontent.com/u/25058208?v=4\" width=\"100;\" alt=\"AHS12\"/\u003e\r\n                    \u003cbr /\u003e\r\n                    \u003csub\u003e\u003cb\u003eAzizul Hakim\u003c/b\u003e\u003c/sub\u003e\r\n                \u003c/a\u003e\r\n            \u003c/td\u003e\r\n            \u003ctd align=\"center\"\u003e\r\n                \u003ca href=\"https://github.com/ajshovon\"\u003e\r\n                    \u003cimg src=\"https://avatars.githubusercontent.com/u/61104583?v=4\" width=\"100;\" alt=\"ajshovon\"/\u003e\r\n                    \u003cbr /\u003e\r\n                    \u003csub\u003e\u003cb\u003eshovon\u003c/b\u003e\u003c/sub\u003e\r\n                \u003c/a\u003e\r\n            \u003c/td\u003e\r\n            \u003ctd align=\"center\"\u003e\r\n                \u003ca href=\"https://github.com/amanullah7649\"\u003e\r\n                    \u003cimg src=\"https://avatars.githubusercontent.com/u/45013120?v=4\" width=\"100;\" alt=\"amanullah7649\"/\u003e\r\n                    \u003cbr /\u003e\r\n                    \u003csub\u003e\u003cb\u003eMD: AMAN ULLAH\u003c/b\u003e\u003c/sub\u003e\r\n                \u003c/a\u003e\r\n            \u003c/td\u003e\r\n\t\t\u003c/tr\u003e\r\n\t\u003ctbody\u003e\r\n\u003c/table\u003e\r\n\u003c!-- readme: contributors -end --\u003e\r\n\r\n## License\r\n\r\nThis 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).\r\n\r\nFeel free to use, modify, and distribute this starter project under the CC0 1.0 license terms. Contributions are welcome to improve this template!\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finnovix-matrix-systems%2Fims-nest-api-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finnovix-matrix-systems%2Fims-nest-api-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finnovix-matrix-systems%2Fims-nest-api-starter/lists"}