HuyAms / awesome-node-boilerplate

Awesome Node boilerplate

A boileplate for REST API focuses on separation of concerns and scalability

Table of content

---

• Features
• Prerequisites
• Getting started
• Project structure
• Testing
• Deployment

Features

---

📂 Separation of concerns & multilayer structure

• Router, Middleware, Controller and Service.
• API response and Error handling.

🚀 Rapid development workflow

• Nodemon
• Winston
• Babel

⚔️ Type checking

• TypeScript

🛡 Testing

• Jest
• Supertest

🔐 Authentication and authorisation

• JSON Web Token - JWT
• Passport local strategy
• Passport Google Strategy
• Sendgrid
• Account validation and activation
• Reset password flow
• Multi-role authorisation

📝 API documentation

• Swagger

🗄 Database integration

• MongoDB
• Mongoose
• CRUD users
• Searching, sorting and pagination

🚓 Security

• HelmetJS
• Express Rate Limit

💎 Rich utilities: Git hooks and code formatting

• Prettier
• Husky
• Lint-staged
• TSLint

🚀 Contious integration

• TravisCI

🏆 Test coverage

Prerequisites

---

• NodeJS.
• MongoDB.
• IDE of your choice.
• Command Line Tools.

Getting started

---

Install dependencies

  npm install

Run MongoDB locally

MacOS

  sudo mongod

Run development server

  npm run dev

Project structure

---

The boilerplate is abstracted to different layers based on the notion of concerns separation and clarity.

Root server file: server.ts

• Initialize Express app, environment variables, logging, global middlewares and routing.
• Run Passport configuration
• Connect to MongoDB

Global middleware: global.ts

This is where we initalize all global middlewares. Those will be used in any routes.

Environment configurations config

Configurations including API keys, environment variables and specific setups for development, production or test env. You can find those in other config files in this directory.

Routers and resources: user and auth

Here is where core of the API is located. Each resouce is divided into different layers:

• Router (resource.router.ts) _ Initialise routes. _ Add specific authorisation and middlewares for each route. * Connect route with equivalent controller
• Interface (resource.interface.ts) * Types that are used by layers of the resource
• Model (resource.model.ts) * Define model for the resource based on database schema.
• Controller (resource.controller.ts) * A bridge between router and service layer. This controller layer take input from client side queries, send to service layer. Then it gets back either data that the client wants, or error in case of failure, and send back to the client.
• Service (resource.service.ts) * The deepest layer of the API where actual database queries and operations are performed. This is also the only layer that does this job.

Server reponse (success or error) apiResponse.ts

Testing

---

Configuration for Jest could be found in jest.config.js.

Running test

Running all test suites with coverage:

  npm run test

Running and watching for changes in one particular test file:

  npm run test:watch src/tests/api/auth/api.test.ts

Deployment

---

Deploy with Heroku

• Install Heroku CLI.
• Create a new app on Heroku Dashboard.
• Login to your Heroku account in command line tool:

  heroku login

• Create a Heroku remote from your app's name:

  heroku git:remote -a your-app-name

• Rename production branch if you want to:

  git remote rename heroku production

• Deploying:

  git push production master