ikigai:nest - server app starter kit

Description

Universal server app starter kit built on top of Nest framework with TypeScript.

Includes:

• Nest Commander
• Nest Schedule
• Nest Swagger
• Nest Validation
• Nest Events
• Nest Bull (queues)
• Nest Config
• Prisma
• Joi
• Passport

Getting started

Create local dev copy for .env file.

cp .env.tpl .env

Replace .env values with desired variables.

Running all services with docker-compose

docker-compose up -d

Installation

$ yarn install

Build for production usage

$ yarn build

Modes

Application could be run in different modes SERVER ro JOBS.

Entrypoint for both modes: src/main.ts.

SERVER

NestApplication apply context and start server on port.

JOBS

Creates NestApplicationContext and infinite loop as worker.

Jobs must be described in cron-way in separate jobs directory.

Read more about NestJS task scheduling.

PROCESSORS

Creates NestApplicationContext and infinite loop as worker-consumer for bull queues.

Starting worker with ProcessorsModule directory.

Read more about NestJS queue consumers.

Running the main in server mode

# development
$ yarn start

# watch mode
$ yarn start:dev

# production mode
$ yarn start:prod

Running jobs app in jobs mode

Precondictions: yarn build

# development
$ yarn start:jobs

Running jobs app in processors mode

Precondictions: yarn build

# development
$ yarn start:processors

Tests

# unit and e2e tests and oneliner
$ yarn test:all

# unit tests
$ yarn test

# e2e tests
$ yarn test:e2e

# test coverage
$ yarn test:cov

Overview

Directory structure

• init/ - directory with .sql files that will executed on init of db running with docker-compose.
• prisma/ - directory for all Prisma files.
• src/ - directory for project sources.
  • commands/ - directory with *.command.ts each one for separate command. More about Nest Commander
  • config/ - directory with configurations for your modules and components. More about Nest Config
  • jobs/ - jobs module. Each service here is aggregation for @Cron handlers. More about Nest Schedule
  • modules/ - directory for application modules. More about Nest Modules
    • auth/ - implementation of auth. More at Auth.
    • identity/ - module that wrap Identity as core auth entity.
  • processors/ - processors module. Each component under the impl directory here is an implementation of @Processor that consume concrete queue. More about Nest Bull (queues)
  • services/ - directory for common application services.
• test/ - directory for e2e tests.

Validation

In general for validation we use Joi and it's schema.

In controllers we work with Validation Pipes to validate and transform incoming data.

So we use composition of both approaches to valiate data in controllers.

Check as example: src/modules/auth/validation.pipe.ts

Usage in controllers:

async register(
    @Body(RegistrationValidationPipe) registrationDto: RegistrationDto
)

Auth

Auth in application built with Passport

src/modules/auth/guards/ - auth guards directory

src/modules/auth/strategies/ - auth strategies directory

Usage in controllers:

@UseGuards(JwtAuthGuard)
@Get('/me')
async me(@Request() req: AuthenticatedRequest): Promise<IdentitySafe> {}

@UseGuards(LocalAuthGuard)
@Post('/sign-in')
async login(@Request() req: AuthenticatedRequest) {}

Events

Events in application build with Nest Events

Guidelines

• create events sub-directory in modules where you emit events from. Check example
• create separate *Listener classes for grouping @OnEvent() handlers over logic scope. Place them in listeners sub-directory where you handle emited events. Check example

Queues

Queus in application build with Nest Bull

Enqueue job

Check example with mailQueue.

Dequeue job

Jobs are consuming by processors

How it works

Queues management operates over Redis Server (cache image in docker-compose.yaml)

Bull Dashboard

Application starts with Bull Board.

By default it's available at localhost:3000/bull.

You can override route by changing env variable BULL_BOARD_PATH;

IDE REST client

Preconditions: VSCODE plugin REST Client or similar in WebStorm.

Presets of requests for most of use-cases stored and available to run in .requests.http

Swagger (OpenAPI)

By default application starts with Swagger UI and available on /docs.

You can change it modifying SWAGGER_PATH in your .env

DB operations

DB management operates with Prisma.

Default driver is mysql but can easily override it with one you prefer.

All prisma files stored in prisma directory in root of project.

In your application use should use prepared dependency PrismaService.

Set it up according to NestJS IoC concepts, e.g:

constructor(private readonly prisma: PrismaService) {}

Useful prisma commands

# Generate artifacts (e.g. Prisma Client)
$ yarn prisma:client

# DO NOT use on production. Create migrations from your Prisma schema, apply them to the database, generate artifacts (e.g. Prisma Client)
$ yarn prisma:dev <MIGRATION_NAME>

# Pull the schema from an existing database, updating the Prisma schema
$ yarn prisma:pull

# Push the Prisma schema state to the database
$ yarn prisma:push

Prisma Studio

Also you could run UI client for simple data management if you prefer.

# Run prisma studio
$ yarn prisma:ui

By default this run instance of Prisma Studio on localhost:5555.

Commands

Application provides it's own CLI commands build with Nest Commander.

# check available commands
$ yarn command -h

# run command
$ yarn command <CMD> [options]

# run command in dev mode without build required (with ts-node)
$ yarn command:ts <CMD> [options]