RESTful API Node Starter Template

A starter template 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, docker support, API documentation etc. For more details, check the features list below.

Quick Start

To create a project, simply run:

npx create-starter-template-nodejs <project-name>

Or

npm init starter-template-nodejs <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/mdashikar/starter-template-nodejs.git
cd starter-template-nodejs
npx rimraf ./.git

Install the dependencies:

npm install

Set the environment variables:

cp .env.example .env

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

Table of Contents

• Features
• Commands
• Environment Variables
• Project Structure
• API Documentation
• Validation
• Authentication
• Authorization
• Logging
• Linting
• Contributing

Features

• NoSQL database: MongoDB object data modeling using Mongoose
• Authentication and authorization: using JWT
• Validation: request data validation using Joi
• Logging: using winston and morgan
• Testing: unit and integration tests using Jest
• 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
• Docker support
• Git hooks: with husky and lint-staged
• Linting: with ESLint and Prettier
• Editor config: consistent editor configuration using EditorConfig

Commands

Running locally:

npm dev

Running in production:

npm start

Testing:

# run all tests
npm test

# run all tests in watch mode
npm test:watch

# run test coverage
npm coverage

Docker:

# run docker container in development mode
npm docker:dev

# run docker container in production mode
npm docker:prod

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

Linting:

# run ESLint
npm lint

# fix ESLint errors
npm lint:fix

# run prettier
npm prettier

# fix prettier errors
npm prettier:fix

Environment Variables

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

# Environment
NODE_ENV=development

# Port number
PORT=3000

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

# JWT
# JWT secret keys
JWT_SECRET=thisisasamplesecret
# Number of minutes after which an access token expires
JWT_ACCESS_EXPIRATION_MINUTES=30
# Number of days after which a refresh token expires
JWT_REFRESH_EXPIRATION_DAYS=30

# SMTP configuration options for the email service
# For testing, you can use a free SMTP service like brevo: https://brevo.com
SMTP_HOST=smtp-relay.brevo.com

SMTP_PORT=587
[email protected]

SMTP_AUTH_PASSWORD=BRGVQs6vacTC37d5
[email protected]

Project Structure

src/
├── app.js              # Express app
├── index.js            # App entry point
├── config/             # Environment variables and configuration
│   ├── config.js
│   └── morgan.js
├── users/              # Users module
│   ├── controllers/
│   │   └── user.controller.js
│   ├── enums/
│   │   └── user.enum.js
│   ├── models/
│   │   └── user.model.js
│   ├── services/
│   │   └── user.service.js
│   └── validators/
│       └── user.validator.js
├── docs/               # Swagger files
│   ├── swagger.json
├── middlewares/        # Custom express middlewares
│   ├── auth.middleware.js
│   └── rateLimiter.middleware.js
├── routes/             # Routes
│   ├── auth.routes.js
│   ├── docs.routes.js
│   └── index.js
└── utils/              # Utility classes and functions
    ├── logger.js
    └── ...

API Documentation

To view the list of available APIs and their specifications, run the server and go to http://localhost:3000/v1/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 available routes:

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

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

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

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

Linting

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

Contributing

Contributions are more than welcome! Please check out the contributing guide.

Inspirations

• hagopj13/node-express-boilerplate
• danielfsousa/express-rest-es2017-boilerplate
• kunalkapadia/express-mongoose-es6-rest-api

License

MIT