NodeJS RESTful API Boilerplate

This is a production-ready skeleton for building RESTful APIs in Node.JS using Express and MongoDB. The skeleton has many built-in features, such as authentication using JWT, request validation, unit and integration tests, continuous integration, API documentation, etc. For more details, please check the features list below.

Features

• NoSQL database: MongoDB object data modeling using Mongoose
• Authentication and authorization: using JWT and Passport
• Two-factor authentication: using Speakeasy
• Validation: request data validation using Express Validator and environment vars validation with Joi
• Files uploading: using Multer
• Email sending: using Nodemailer
• SMS sending: using Twilio
• Logging: using Winston and Morgan
• Testing: unit and integration tests using Jest and SuperTest and mocks with node-mocks-http
• Error handling: centralized error handling mechanism
• API documentation: with swagger-jsdoc and swagger-ui-express or with Postman and docgen
• Process management: advanced production process management using PM2
• Dependency management: with Yarn
• Environment variables: using dotenv
• Security: set security HTTP headers using Helmet
• Sanitizing: sanitize request data against xss and query injection
• CORS: Cross-Origin Resource-Sharing enabled using Cors
• Compression: gzip compression with Compression
• CI: continuous integration with Github actions
• Code coverage: using Coveralls
• Git hooks: with Husky and Lint-staged
• Git commit: with Conventional commit messages using Commitizen
• Linting: with ESLint and Prettier
• Editor config: consistent editor configuration using EditorConfig

Requirements

• Node.js v16.14.2+
• Yarn v1.22.18+
• MongoDB v4.4.1+
• Install Node.js using Node Version Manager

Quick Start

Clone the repo and make it yours

git clone https://github.com/dejosli/NodeJS-RESTful-API-Boilerplate.git
cd NodeJS-RESTful-API-Boilerplate
rm -rf .git

Install Yarn

npm install -g yarn # if yarn is not installed

Install dependencies

yarn install
or
yarn install --frozen-lockfile # recommended

Set environment variables

cp .env.example .env

# open .env and modify the environment variables (if needed)

Folder Structure

src
│   index.js
│
├───api
│   ├───controllers
│   │   └───tests
│   ├───docs
│   ├───lib
│   │   └───tests
│   ├───middleware
│   ├───models
│   │   └───plugins
│   ├───routes
│   │   └───v1
│   ├───services
│   │   └───tests
│   ├───utils
│   │   └───tests
│   ├───validators
│   │   └───tests
│   └───workers
├───config
├───core
└───tests

How to Run

Running Locally

yarn dev

Running in Production

yarn start

Response Format

Success Response

{
  "success": true,
  "code": 200,
  "message": "Success Response Message",
  "data": {}
}

Error Response

{
  "success": false,
  "code": 400,
  "message": "Error Response Message",
  "errors": [
    {
      "field": "phoneNumber",
      "message": "Phone number already exists for another user."
    }
  ]
}

Commands

Linting

Linting is done using ESLint and Prettier.

# lint code with ESLint
yarn lint

# try to fix ESLint errors
yarn lint:fix

# style code with Prettier
yarn prettier

# try to fix Prettier errors
yarn prettier:fix

In this project, ESLint is configured to follow the Airbnb JavaScript style guide with some modifications. It also extends eslint-config-prettier and eslint-plugin-security to turn off all rules that are unnecessary or might conflict with Prettier.

To modify the ESLint configuration, update the .eslintrc.json file. To modify the Prettier configuration, update the .prettierrc.json file.

To prevent a certain file or directory from being linted, add it to .eslintignore and .prettierignore.

To maintain a consistent coding style across different IDEs, the project contains .editorconfig

Testing

# run all tests
yarn test

# run all tests in watch mode
yarn test:watch

# run test coverage
yarn test:coverage

# run test coverage with coveralls
yarn test:coveralls

Conventional Commits

# add all changes to staged
git add .

# run for conventional commits message
yarn commit

Husky Install

yarn prepare

List of things that need to be done

• Test the utilities
• Test the libraries
• Test the validators
• Test the middleware
• Test the services
• Test the controllers
• Test the API's endpoints

Inspirations

• hagopj13/node-express-boilerplate
• danielfsousa/express-rest-es2017-boilerplate
• diegohaz/rest
• maitraysuthar/rest-api-nodejs-mongodb
• madhums/node-express-mongoose
• kunalkapadia/express-mongoose-es6-rest-api

Bugs or improvements

Every project needs improvements, Feel free to report any bugs or improvements. Pull requests are always welcome.

License

Open-sourced software licensed under the MIT License