Node.JS Boilerplate - JavaScript RESTful APIs

A production ready boilerplate/starter project for quickly building RESTful APIs using Node.js, Express, and Mongoose. Authentication using JWT, request validation, unit and integration tests, continuous integration, docker support, API documentation, pagination, etc. For more details, check the features list below.

Quick Start

To initialize simply run:

./init.sh

You may need to make the init.sh file executable by running following command before running ./init.sh.

chmod u+x ./init.sh

Manual Installation

If you would still prefer to do the installation manually, follow these steps:

Run the following command.

npm install

or

yarn install

Set the environment variables:

cp .env.example .env

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

Table of Contents

• Features
• Commands
• Environment Variables
• Project Structure
• API Documentation
• Error Handling
• Validation
• Authentication
• Authorization
• Logging
• Custom Mongoose Plugins
• Linting
• Contributing

Functionalities

• Database: MongoDB object data modeling using Mongoose
• Authentication and authorization: using passport
• Validation: request data validation using Joi
• Logging: using winston and morgan
• Testing: unit and integration tests using Jest
• Error handling: error handling mechanism is centralized
• API documentation: with swagger-jsdoc and swagger-ui-express
• Process management: advanced production process management using PM2
• Dependency management: with NPM
• Environment variables: using dotenv and cross-env
• Security: set security HTTP headers using helmet
• Santizing: 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 Travis CI
• Docker support
• Code coverage: using coveralls
• Git hooks: with husky and lint-staged
• Linting: with ESLint

Commands

Running locally:

npm run dev

Running in production:

npm start

Testing:

# run all tests
npm run test

# run all tests in watch mode
npm run test:watch

# run test coverage
npm run coverage

Docker:

# run docker container in development mode
npm run docker:dev

# run docker container in production mode
npm run docker:prod

# run all tests in a docker container
npm run docker:test

Linting:

# run ESLint
npm run lint

# fix ESLint errors
npm run lint:fix

Environment Variables

The environment variables can be found and modified in the .env file. They come with these default values:

# Node server port number
PORT=8080

# Frontend Site URL
SITE_URL=http://localhost:3000

# URL of the Mongo DB
MONGODB_URL=mongodb://127.0.0.1:27017/node-boilerplate

# JWT
# JWT secret key
JWT_SECRET=SuperSecretShhhhhhhhhhh
# Number of minutes after which an access token expires default 1440 minutes i.e. 24 hours
JWT_ACCESS_EXPIRATION_MINUTES=1440
# Number of minutes after which a reset password token expires
JWT_RESET_PASSWORD_EXPIRATION_MINUTES=60
# Number of minutes after which a verify email token expires
JWT_VERIFY_EMAIL_EXPIRATION_MINUTES=60

# Email configuration
# Service Provider => smtp, sendgrid, aws
EMAIL_PROVIDER=smtp
# Service Provider Key ID => Only for aws mailer
EMAIL_PROVIDER_KEY_ID=NA
# Service Provider Key => Only for sendgrid and aws mailer
EMAIL_PROVIDER_KEY=NA
# SMTP configuration options for the email service
# For testing, you can use a fake SMTP service like Ethereal: https://ethereal.email/create
SMTP_HOST=smtp.ethereal.email
SMTP_PORT=587
SMTP_USERNAME=something@ethereal.email
SMTP_PASSWORD=email-password
EMAIL_FROM=support@yourapp.com

Project Structure

src\
 |--config\         # Environment variables and configuration related things
 |--controllers\    # Route controllers (controller layer)
 |--docs\           # Swagger files
 |--middlewares\    # Custom express middlewares
 |--models\         # Mongoose models (data layer)
 |--routes\         # Routes
 |--services\       # Business logic (service layer)
 |--utils\          # Utility classes and functions
 |--validations\    # Request data validation schemas
 |--app.js          # Express app
 |--index.js        # App entry point

API Documentation

To view the list of available APIs and their specifications, run the server and go to http://localhost:8080/docs in your browser. This documentation page is automatically generated using the swagger definitions written as comments in the route files.

API Endpoints

List of routes added by default:

Auth routes:
POST /auth/register - register
POST /auth/login - login
POST /auth/forgot-password - send reset password email
POST /auth/reset-password - reset password
POST /auth/send-verification-email - send verification email
POST /auth/verify-email - verify email

User routes:
POST /users - create a user
GET /users - get all users
GET /users/:userId - get user
PATCH /users/:userId - update user
PATCH /users/org/:orgId - update organization
DELETE /users/:userId - delete user

Please make sure to follow the same routing path patterns in any other modules that you will be adding.

E.g. Documents module will have base path /products and sample routes will be as given below.

POST /products - create a product
GET /products - get all products
GET /products/:productId - get product
PATCH /products/:productId - update product
DELETE /products/:productId - delete product

Error Handling

The app has a centralized error handling mechanism.

Controllers should try to catch the errors and forward them to the error handling middleware (by calling next(error)). For convenience, you can also wrap the controller inside the catchAsync utility wrapper, which forwards the error.

const catchAsync = require('../utils/catchAsync');

const controller = catchAsync(async (req, res) => {
  // this error will be forwarded to the error handling middleware
  throw new Error('Something wrong happened');
});

The error handling middleware sends an error response, which has the following format:

{
  "code": 404,
  "message": "Not found"
}

When running in development mode, the error response also contains the error stack.

The app has a utility ApiError class to which you can attach a response code and a message, and then throw it from anywhere (catchAsync will catch it).

For example, if you are trying to get a user from the DB who is not found, and you want to send a 404 error, the code should look something like:

const httpStatus = require('http-status');
const ApiError = require('../utils/ApiError');
const User = require('../models/User');

const getUser = async (userId) => {
  const user = await User.findById(userId);
  if (!user) {
    throw new ApiError(httpStatus.NOT_FOUND, 'User not found');
  }
};

Validation

Request data is validated using Joi. Check the documentation for more details on how to write Joi validation schemas.

The validation schemas are defined in the src/validations directory and are used in the routes by providing them as parameters to the validate middleware.

const express = require('express');
const validate = require('../../middlewares/validate');
const userValidation = require('../../validations/user.validation');
const userController = require('../../controllers/user.controller');

const router = express.Router();

router.post('/users', validate(userValidation.createUser), userController.createUser);

Authentication

To require authentication for certain routes, you can use the auth middleware.

const express = require('express');
const auth = require('../../middlewares/auth');
const userController = require('../../controllers/user.controller');

const router = express.Router();

router.post('/users', auth(), userController.createUser);

These routes require a valid JWT access token in the Authorization request header using the Bearer schema. If the request does not contain a valid access token, an Unauthorized (401) error is thrown.

Generating Access Tokens:

An access token can be generated by making a successful call to the register (POST /auth/register) or login (POST /auth/login) endpoints.

An access token is valid for 1440 minutes (24 hours). You can modify this expiration time by changing the JWT_ACCESS_EXPIRATION_MINUTES environment variable in the .env file.

Authorization

The auth middleware can also be used to require certain rights/permissions to access a route.

const express = require('express');
const auth = require('../../middlewares/auth');
const userController = require('../../controllers/user.controller');

const router = express.Router();

router.post('/users', auth('manageUsers'), userController.createUser);

In the example above, an authenticated user can access this route only if that user has the manageUsers permission.

The permissions are role-based. You can view the permissions/rights of each role in the src/config/roles.js file.

If the user making the request does not have the required permissions to access this route, a Forbidden (403) error is thrown.

Logging

Import the logger from src/config/logger.js. It is using the Winston logging library.

Logging should be done according to the following severity levels (ascending order from most important to least important):

const logger = require('<path to src>/config/logger');

logger.error('message'); // level 0
logger.warn('message'); // level 1
logger.info('message'); // level 2
logger.http('message'); // level 3
logger.verbose('message'); // level 4
logger.debug('message'); // level 5

In development mode, log messages of all severity levels will be printed to the console.

In production mode, only info, warn, and error logs will be printed to the console.
It is up to the server (or process manager) to actually read them from the console and store them in log files.
This app uses pm2 in production mode, which is already configured to store the logs in log files.

Note: API request information (request url, response code, timestamp, etc.) are also automatically logged (using morgan).

Custom Mongoose Plugins

The app also contains 3 custom mongoose plugins that you can attach to any mongoose model schema. You can find the plugins in src/models/plugins.

const mongoose = require('mongoose');
const { private, paginate, softDelete } = require('./plugins');

const userSchema = mongoose.Schema(
  {
    /* schema definition here */
  },
  { timestamps: true }
);

userSchema.plugin(softDelete);
userSchema.plugin(private);
userSchema.plugin(paginate);

const User = mongoose.model('User', userSchema);

private

The private plugin applies the following changes in the private transform call:

• removes __v, and any schema path that has private: true

softDelete

The softDelete plugin adds additional delete methods to the mongoose schema to not permanently delete records, instead add a deleted flag. This plugin also overrides find, count and countDocuments methods of mongoose schema to eliminate records having deleted flag true.

paginate

The paginate plugin adds the paginate static method to the mongoose schema.

Adding this plugin to the User model schema will allow you to do the following:

const queryUsers = async (filter, options) => {
  const users = await User.paginate(filter, options);
  return users;
};

The filter param is a regular mongo filter.

The options param can have the following (optional) fields:

const options = {
  sortBy: 'name:desc', // sort order
  limit: 5, // maximum results per page
  page: 2, // page number
  populate: [{ 
    path: "_org", 
    select: "name email" 
  }] // array of fields to populate with field path and fields to select
};

The plugin also supports sorting by multiple criteria (separated by a comma): sortBy: name:desc,role:asc

The paginate method returns a Promise, which fulfills with an object having the following properties:

{
  "results": [],
  "page": 2,
  "limit": 5,
  "totalPages": 10,
  "totalResults": 48
}

Linting

Linting is done using ESLint and Prettier.

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

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