Have ideas to improve npm?Join in the discussion! »


    1.2.1 • Public • Published

    RESTful API Node Server Boilerplate

    Build Status Coverage Status Codacy Badge PRs Welcome

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

    By running a single command, you will get a production-ready Node.js app installed and fully configured on your machine. The app comes with many built-in features, such as 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 create a project, simply run:

    npx express-app-boilerplate <project-name>


    npm init express-app-boilerplate <project-name>

    Manual Installation

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

    Clone the repo:

    git clone --depth 1 https://github.com/UAhmadSoft/express-app-boilerplate.git
    cd node-express-boilerplate
    npx rimraf ./.git

    Install the dependencies:

    yarn install

    Set the environment variables:

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

    Table of Contents


    • NoSQL database: MongoDB object data modeling using Mongoose
    • Authentication and authorization: using JWT
    • Logging: morgan
    • Testing: unit and integration tests using Jest
    • Error handling: centralized error handling mechanism
    • Process management: advanced production process management using PM2
    • Dependency management: with Yarn
    • 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
    • Code quality: with Codacy
    • Git hooks: with husky and lint-staged
    • Linting: with ESLint and Prettier
    • Editor config: consistent editor configuration using EditorConfig


    Running locally:

    yarn dev

    Running in production:

    yarn start


    # run all tests
    yarn test
    # run all tests in watch mode
    yarn test:watch
    # run test coverage
    yarn coverage


    # run docker container in development mode
    yarn docker:dev
    # run docker container in production mode
    yarn docker:prod
    # run all tests in a docker container
    yarn docker:test


    # run ESLint
    yarn lint
    # fix ESLint errors
    yarn lint:fix
    # run prettier
    yarn prettier
    # fix prettier errors
    yarn prettier:fix

    Environment Variables

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

    # PORT
    # Sendgrid Details
    Email_From = yourEmail@gmail.com
    Sendgrid_Password =SA.assddsd.ssdsddsd
    Sendgrid_Username =yourSendGridUsername
    # JWT

    Project Structure

     |--config\         # Environment variables and configuration related things
     |--controllers\    # Route controllers (controller layer)
     |--middlewares\    # Custom express middlewares
     |--models\         # Mongoose models (data layer)
     |--routes\         # Routes
     |--utils\          # Utility classes and functions
     |--app.js          # Application/Node Js Stuff
     |--server.js        # App entry point , Express related Stuff

    API Endpoints

    List of available routes:

    Auth routes:
    POST api/v1/signUp - register
    POST api/v1/login - login
    POST api/v1/forgotPassword - send reset password email
    POST api/v1/resetPassword - reset password
    POST api/v1/confirmMail - verify email

    User routes:
    POST api/v1/users - create a user
    GET api/v1/users - get all users
    GET api/v1/users/:userId - get user
    PATCH api/v1/users/:userId - update user
    DELETE api/v1/users/:userId - delete user

    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 AppError(httpStatus.NOT_FOUND, 'User not found');


    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 /v1/auth/register) or login (POST /v1/auth/login) endpoints. The response of these endpoints also contains refresh tokens (explained below).

    An access token is valid for 30 minutes. You can modify this expiration time by changing the JWT_ACCESS_EXPIRATION_MINUTES environment variable in the .env file.

    Refreshing Access Tokens:

    After the access token expires, a new access token can be generated, by making a call to the refresh token endpoint (POST /v1/auth/refresh-tokens) and sending along a valid refresh token in the request body. This call returns a new access token and a new refresh token.

    A refresh token is valid for 30 days. You can modify this expiration time by changing the JWT_REFRESH_EXPIRATION_DAYS environment variable in the .env file.


    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.


    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).


    Linting is done using ESLint and Prettier.

    In this app, ESLint is configured to follow the Airbnb JavaScript style guide with some modifications. It also extends eslint-config-prettier 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


    Contributions are more than welcome!





    npm i express-app-boilerplate

    DownloadsWeekly Downloads






    Unpacked Size

    124 kB

    Total Files


    Last publish


    • avatar