TypeScript Express Microservice Template

A delightful way of building a Node.js Backend Microservice with beautiful code written in TypeScript.
_{Made with ❤️ by Kingshuk Nandy}

❯ Why

This project is a complete Backend Microservice Application Server build in NodeJS with all standard features. We like you to be focused on your business and not spending hours in project configuration.

Try it!! We are happy to hear your feedback or any kind of new features.

❯ Application Flow

❯ Features

• Authentication of the API is integrated using JWT
• Strong Password Encryption using bcrypt
• Basic Unit testing is implemented using jest
• Simplified Database Query with the ORM Sequelize.
• API Documentation thanks to swagger
• PostgreSQL database provides a powerful Object Relational Database
• GraphQL provides as a awesome query language for our api GraphQL.
• Deployment Using Docker and Docker Compose

❯ Table of Contents

• Getting Started
• Scripts and Tasks
• Important URL
• API Routes
• Project Structure
• Logging
• Seeding
• Role based Access
• GraphQL
• Docker
• Docker Compose
• Further Documentations
• License

Getting Started

Step 1: Set up the Development Environment

You need to set up your development environment before you can do anything.

Install Node.js and NPM

Step 2: Set up Application Database

Get your application DB up. Ensure that you have docker installed. We are using Postgres Docker container as the Database

docker pull postgres

docker run --name postgres-db -p 5432:5432 -e POSTGRES_PASSWORD=password -d postgres

Step 2: Create new Project

Fork or download this project. Configure your package.json for your new project.

Then copy the .env.example file and rename it to .env. In this file you have to add your database connection information.

Create a new database with the name you have in your .env-file.

Then setup your application environment.

❯ Scripts and Tasks

All script are defined in the package.json file, but the most important ones are listed here.

Install

• Install all dependencies with npm install

Linting

• For linting execute the command npm run eslint:fix

Tests

• Run the unit tests using npm test

Running in dev mode

• Run npm run dev to start nodemon with ts-node, to serve the app.

Building the project and run it

• Then start the application

npm run start:dev

❯ Important URL

• Application Health http://localhost:3000/health
• Graphql Server
  • http://localhost:3000/graphql or
  • https://studio.apollographql.com/sandbox/explorer?endpoint=http://localhost:3000/graphql
• Swagger http://localhost:3000/api-docs/

In order to access the private the routes, we need to pass the JWT token generated by the login API

❯ API Routes

The route prefix is /api by default, but you can change this in the .env file. The swagger and the monitor route can be altered in the .env file.

Route	Description
/health	Get the health of server
/apis/v1	The Api server details
/graphql	Route to the graphql editor or your query/mutations requests
/api-docs/	This is the Swagger UI with our API documentation

Example Entity Endpoint

# Public API Routes:
+--------+------------------------------+
  Method | URI
+--------+------------------------------+
  GET    | /health
  POST   | /apis/v1/auth/signUp
  POST   | /apis/v1/auth/login
  GET    | /apis/v1/employees/getEmployeeBasic
  GET    | /apis/v1/employees/getEmployees
  POST   | /apis/v1/employees/setEmployee
+--------+------------------------------+

# Private API Routes:
+--------+------------------------------+
  Method | URI
+--------+------------------------------+
  GET    | /apis/v1/users/getUsersBasic
  GET    | /apis/v1/users/getUsers
  POST   | /apis/v1/users/setUser
+--------+------------------------------+

❯ Project Structure

Name	Description
.vscode/	VSCode tasks, launch configuration and some other settings
dist/	Compiled source files will be placed here
src/	Source files
src/constants/	The Global Constants
src/controllers/	REST API Controllers
src/controllers/v1	REST API Controllers version v1
src/dbServices/v1	DB Service Configuration
src/services/	Service layer
src/middlewares/	Express Middlewares like Authentication
src/models/	Sequelize Models
src/routes/v1Apis	API Routes
test/unit/ *.test.ts	Unit tests
.env.example	Environment configurations

❯ Logging

Our logger is winston.

export interface Log {
  level: "info" | "debug" | "error" | "warn";
}
const logger = winston.createLogger({
  transports: [new winston.transports.Console({ level: LOG.level })],
});
export default logger;

❯ Seeding

Yet to be implemented

❯ Role Based Access

Yet to be implemented

❯ GraphQL

For the GraphQL part we used the library Apollo Server 4 to build awesome GraphQL API's.

First you need to login with username and password

  mutation SampleQuery {
    login(email:"rama.sharma@gmail.com",password:"test@1234"){
      token
      email
      name
    }
}

Then we need to pass this token as a header for every graphql call

query getAllTheUsers{
  getAllUsers {
    name
    email
  }
}

❯ Docker

Here we will try to spin up two containers.

• postgres
• microservice There has to be a common network attached to both of them so that they will be able to communicate with each other

Step A: Install Docker

Before you start, make sure you have a recent version of Docker installed

Step B: Create a network

In order to communicate between containers we need to create a user-defined custom bridge networks

  docker network create -o com.docker.network.bridge.enable_icc=true custom-network

Step C: Run the Database Image

Then, Get the Postgres DB up. Run the postgres image, passing the newly created network custom-network

docker run --network custom-network --name postgres-db -p 5432:5432 -e POSTGRES_PASSWORD=password postgres

Step D: Build the Application Docker image

docker build -t <your-image-name> .

Then, build the app's image

docker build . -t kingshuknandy/node-microservice

Set E: Run the Application docker image in container and map port

Finally, run the app's image, passing the newly created network custom-network

The port which runs your application inside Docker container is either configured as PORT property in your .env configuration file or passed to Docker container via environment variable PORT. Default port is 3000.

docker run -p 3000:3000 --network custom-network --env-file .env  --env DB_HOST='postgres-db' --name node-microservice kingshuknandy/node-microservice:latest

❯ Docker Compose

• Created the Dockerfile to build the app
• Defined the services that make up the app in docker-compose.yml so they can be run together in an isolated environment.
• Run docker-compose up and Compose starts and runs your entire app.

docker-compose up

❯ Further Documentations

Name & Link	Description
Express	Express is a minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications.
Sequelize	Sequelize is a modern TypeScript and Node.js ORM for Oracle, Postgres, MySQL
Jest	Delightful JavaScript Testing Library for unit and e2e tests
swagger Documentation	API Tool to describe and document your api.
GraphQL Documentation	A query language for your API.

❯ References

❯ License

MIT