README.md

Blog made using Nestjs + Mikro-orm codebase(backend) containing real world examples (CRUD, auth (password based and oauth), advanced patterns, etc) and batteries included and ever-evolving

NOTE: Starting April 18,2022 , the repo has ditched most promises for observables. You can check the latest promised version code at commit

More on why observables are better than promises can be read here

Table of Contents

• Whats included
• Prerequisites
• Getting Started
• Available Scripts
• Setup
• File Structure
• Authentication
• Deployment

Whats included

• 🌐 I18n - Internationalization
• 🧵 Stats - Swagger stats for common server metrics
• 🧵 Poolifier - Threads for CPU extensive tasks
• 💬 Twilio - SMS support
• 📱 NestJS — Latest version
• 🎉 TypeScript - Type checking
• ⚙️ Dotenv - Supports environment variables
• 🗝 Authentication, RSA256, [OAuth](https://oauth.net/ - JWT, RSA256, OAuth
• 🏬 Authorization - RBAC with casl
• 🏪 MikroORM - Database ORM
• 🏪 PostgreSQL - Open-Source Relational Database
• 🧠 Configuration - Single config for all
• 📃 Swagger - API Documentation
• 🐳 Docker Compose - Container Orchestration
• 🔐 Helmet - Secure HTTP headers
• 📏 ESLint — Pluggable JavaScript linter
• ✅ Commitlint — Checks if your commit messages meet the conventional commit format.
• 🐺 Husky — Helps you create Git hooks easily.

Prerequisites

NodeJS https://nodejs.org/en/

Typescript https://www.typescriptlang.org/

PostgresQL https://www.postgresql.org/

Redis https://redis.io/

RabbitMQ https://www.rabbitmq.com

Getting started

# 1. Clone the repository or click on "Use this template" button.
npx degit rubiin/ultimate-nest my-nest-app

# 2. Enter your newly-cloned folder.
cd ultimate-nest

# 3. Create Environment variables file.
cp env/.env.sample env/.env.dev

# 4. Install dependencies (preferred: pnpm)
 pnpm install
 npm install
 yarn install

Note

If you face any issues with dependencies when using yarn or npm, stick to pnpm for now

Note

Env files are kept in env folder. The config validation allows 4 environment ['dev', 'prod', 'test','stage']. The env file name should be of format .env.[environment] Ex. (.env.dev). The env to use should be provided while running any script as NODE_ENV=dev npm run dev

Available Scripts

• npm run start - Start application
• npm run start:dev - Start application in watch mode
• npm run start:prod - Start built application
• npm run start:hmr - Start application with hot module replacement
• npm run lint - Uses eslint to lint all the files inside src with config provided in eslint.config.js
• npm run orm migration:create - Uses Mikroorm to create a migration file
• npm run orm migration:up - This command is used to run availablexisting migration files.
• npm run orm migration:down - This command is used to rollback migration.
• npm run orm seeder:run - This command is used to run existing seeders in src/common/database.

All the scripts require NODE_ENV flag

Additionally, you can also see the scripts in justfile which is a cross platform task runner. You can use it by installing just and then running just <script>. Ex. just build

---

Setup

• First if you don't want to use any libs from like redis, mailer etc. replace them from the config.module.ts
  • You will also need to remove the config from validate.config.ts from line load: []
  • Also remove the unwanted config variables from the env file

Migration and seeding(optional)

Migrations are used to update the database schema. The migration files are stored in migrations directory.

NODE_ENV=dev npm run orm migration:up # applies migration for dev env

Seeding is used to insert data into the database. The seeding files are stored in common/database/seeders directory.

USER_PASSWORD=Test@1234 NODE_ENV=dev npm run orm seeder:run   # seeds data for dev env with all user password set as Test@1234

Seeding is optional

Start application

• NODE_ENV=dev npm run start
• View automatically generated swagger api docs by browsing to http://localhost:[port]/docs
• View automatically generated swagger stats dashboard by browsing to http://localhost:[port]/stats. The username and password is the values set in the env file under SWAGGER_USERNAME and SWAGGER_PASS respectively

File structure

ultimate-nest
├── env                                           * Contains all configuration files
│   └── .env.example                              * Sample configuration file.
│   └── .env.dev                                  * Configuration file for development environment.
│   └── .env.prod                                 * Configuration file for production environment.
│   └── .env.test                                 * Configuration file for test environment.
├── coverage                                      * Coverage reports after running `npm run test:cov` command.
├── dist                                          * Optimized code for production after `npm run build` is run.
├── src
    └── modules                                   * Folder where specific modules all files are stored
          └── <module>
      │       └── dto                             * Data Transfer Objects.
      │       └── <module>.controller.ts          * Controller file.
      │       └── <module>.module.ts              * root module file for module.
      │       └── <module>.service.ts             * Service file for <module>.
      │       └── <module>.service.spec.ts        * Test file for service.
      │       └── <module>.repository.ts          * Repository file for <module>.
      │       └── <module>.repository.spec.ts     * Test file for repository.
│   └── common                                    * Common helpers function, dto, entity,guards, custom validators,types, exception, decorators etc.
│   └── __mocks__                                 * Fixtures for unit tests.
│   └── libs                                      * Resusable pre configured libraries
│   └── resources                                 * Contains all static resources like ssl, i18n,email templates etc.
│   └── app.module.ts                             * Root module of the application.
│   └── main.ts                                   * The entry file of the application which uses the core function NestFactory to create a Nest application instance.
├── test                                          * End to end test files for the application.

Authentication

This applications uses JSON Web Token (JWT) to handle authentication. The token is passed with each request using the Authorization header with Token scheme. The JWT authentication middleware handles the validation and authentication of the token.

Deployment

You need to have docker and docker-compose installed. The image environment variable values can be found at the compose file

ENV=dev sh ./scripts/deploy.sh   # deploys dev environment (.env.dev used)
ENV=prod sh ./scripts/deploy.sh   # deploys prod environment (.env.prod used)

More docs found at docs folder

Do you use this template?
Don't be shy to give it a star! ★

Support

Also if you are into NestJS ecosystem you may be interested in one of my other libs:

helper-fns

A collection of helper functions for typescrip development. It includes functions for array,object,string,etc

nestjs-easyconfig

Platform config manager for nestjs. It supports multiple config files and environment variables.

---

nestjs-minio

This is a minio module for Nest.

---

nestjs-cloudinary

This is a cloudinary module for Nest.

---

nestjs-pgpromise

A Module for Utilizing Pg-promise with NestJS

---

Star History

Made with ❤️ with opensource.