search

NeoSOFT-Technologies / rest-node-nestjs

With this skeleton, we can easily start a server application using Node.js, Nest JS and TypeScript.
https://neosoft-technologies.github.io/rest-node-nestjs/
Apache License 2.0
54 stars 36 forks source link
best-practices boilerplate docker jest nestjs node nodejs restful-api typeorm typescript

readme

Nest JS Skeleton for REST Application Quality Gate Status CI

A skeleton/boilerplate/starter project for quickly building RESTful APIs using Node.js, NestsJS, Express, and MySQL.

By running one command, you will get a production-ready Node.js app installed and configured on your machine. There are many built-in features in the skeleton, including authentication using JWT, request validation, unit and integration tests, continuous integration, docker support, API documentation, pagination, etc. To learn more about its features, check out the following list.

Description

Take it for a test drive. We'd love to hear any feedback you have or if you've thought of a new feature.

Table of Contents

Features

Getting started

Prerequisites

Setup

To get started, clone the repository to your local computer. Use the following command to run in your terminal.

Clone The Application

// clone the application
$ git clone https://github.com/NeoSOFT-Technologies/rest-node-nestjs.git

Install The Dependencies

Next, install the packages that are required for this project.

// Install the required npm modules
$ npm install

Create The Environment Variables

The config/env/.env file should be placed in root folder with the following variables.

# config/env/.env.example

APP_NAME=rest_api
NODE_ENV=dev
DB_HOST=127.0.0.1
DB_DATABASE=rest_api
DB_USER=user
DB_PASSWORD=root
DB_PORT=3306

Start MySQL Database

In order to use mysql, you need to have it installed in your local machine. Docker Compose is what we will be using in our case, In the project directory, execute the following command.

# build images, create and run containers in background
docker-compose -f ./docker/docker-compose.yml --env-file ./config/env/.env up -d

In order to apply your modified code to a running container, you should add a build option.

# if source code is changed, rebuild image, recreate and start container
docker-compose  -f ./docker/docker-compose.yml --env-file ./config/env/.env up -d --build

Running the app

# development
$ npm run start

# watch mode
$ npm run start:dev

# production mode
$ npm run start:prod

Test

For this project, We chose Jest as our test framework. While Mocha is probably more common, Mocha seems to be looking for a new maintainer and setting up TypeScript testing in Jest is wicked simple.

# unit tests
$ npm run test

# e2e tests
$ npm run test:e2e

# test coverage
$ npm run test:cov

Running the build

All the different build steps are orchestrated via npm scripts. Npm scripts basically allow us to call (and chain) terminal commands via npm. This is nice because most JavaScript tools have easy to use command line utilities allowing us to not need grunt or gulp to manage our builds. If you open package.json, you will see a scripts section with all the different scripts you can call. To call a script, simply run npm run <script-name> from the command line. You'll notice that npm scripts can call each other which makes it easy to compose complex builds out of simple individual build scripts. Below is a list of all the scripts this template has available:

Npm Script Description
build Full build. Runs ALL build tasks
start:debug Performs a full build and then serves the app in watch mode
lint Runs ESLint on project files
format Runs the file formatter
serve Runs node on dist/server.js which is the apps entry point
start Does the same as 'npm run serve'. Can be invoked with npm start
test Runs tests using Jest test runner
test:watch Runs tests in watch mode
doc Generate the project documenation using compdoc

Project Structure

In a TypeScript project, it's best to have separate source and distributable files. TypeScript (.ts) files live in your src folder and after compilation are output as JavaScript (.js) in the dist folder. The test and views folders remain top level as expected.

Please find below a detailed description of the app's folder structures:

Note! Make sure you have already built the app using npm run build

Name Description
.vscode Contains VS Code specific settings
.github Contains GitHub settings and configurations, including the GitHub Actions workflows
dist Contains the distributable (or output) from your TypeScript build. This is the code you ship
node_modules Contains all your npm dependencies
src Contains your source code that will be compiled to the dist dir
src/config | Here you will find all the environment configuration necessary to access the application e.g. .env
src/components Components define group of files/source that respond to various module(http requests)
src/components/${module_name}/dto/ DTO (Data Transfer Object) Schema, Validation
src/components/${module_name}/entities/ Entities belongs to that Component
src/components/${module_name}/repository/ Repository belongs to that Component
src/components/${module_name}/services/ Services belongs to that Component
src/components/${module_name}/module_name.controllers.ts Controller belongs to that Component
src/components/${module_name}/module_name.module.ts Module belongs to that Component
src/core All core modules - Guards, Http Request & Response Handler, Logger
src/main.ts Entry point to your express app
test Contains your tests. Separate from source because there is a different build process.
config/env/.env.example API keys, tokens, passwords, database URI. Clone this, but don't check it in to public repos.
package.json File that contains npm dependencies
tsconfig.json Config settings for compiling server code written in TypeScript
tsconfig.build.json Config settings for compiling tests written in TypeScript
.eslintrc Config settings for ESLint code style checking
.eslintignore Config settings for paths to exclude from linting

Documentation

1. Generation with compdoc

Generate project documentation using the following command (npm 6 is required for npx support). See the official documentation for more options.

npm run doc

OR

npx @compodoc/compodoc -p tsconfig.json -s

2. Request and Response Cycle

An explanation of how the request and response cycle works is provided here

2.1 Request and Response Workflow

Boilerplate has a custom guard enabled for handling response and request for every api. The integration of request response guard is enabled by default with response structure

Request and Response Cycle

2.2 Request Workflow

By creating a workflow, you can specify the template that should be used to create a change request when a request for service is logged.

Request Workflow

3. Modules

3. Modules

Miscellaneous

Trainings

Video Tutorials

Below are the video tutorial links for the modules that we have implemented in the boilerplate.

The Below list is the demonstration Videos of the various modules in the nestjs boilerplate.

The below list will tell us how to create components in the boilerplate.

Testing Videos

Contributing To This Project

Contributions are welcome from anyone and everyone. We encourage you to review the guiding principles for contributing

Issues and Discussions

Stay in touch