Express & mongoose REST API Boilerplate in ES6 with Code Coverage

Sponsor

You can support the project by checking out our sponsor page. It takes only one click:

Overview

This is a boilerplate application for building REST APIs in Node.js using ES6 and Express with Code Coverage and JWT Authentication. Helps you stay productive by following best practices. Follows Airbnb's Javascript style guide.

Heavily inspired from Egghead.io - How to Write an Open Source JavaScript Library.

Features

• CORS support via cors
• Uses http-status to set http status code. It is recommended to use httpStatus.INTERNAL_SERVER_ERROR instead of directly using 500 when setting status code.
• Has .editorconfig which helps developers define and maintain consistent coding styles between different editors and IDEs.

Getting Started

Clone the repo:

git clone [email protected]:kunalkapadia/express-mongoose-es6-rest-api.git
cd express-mongoose-es6-rest-api

Install yarn:

npm install -g yarn

Install dependencies:

yarn

Set environment (vars):

cp .env.example .env

Start server:

# Start server
yarn start

# Selectively set DEBUG env var to get logs
DEBUG=express-mongoose-es6-rest-api:* yarn start

Refer debug to know how to selectively turn on logs.

Tests:

# Run tests written in ES6 
yarn test

# Run test along with code coverage
yarn test:coverage

# Run tests on file change
yarn test:watch

# Run tests enforcing code coverage (configured via .istanbul.yml)
yarn test:check-coverage

Lint:

# Lint code with ESLint
yarn lint

# Run lint on any file change
yarn lint:watch

Other gulp tasks:

# Wipe out dist and coverage directory
gulp clean

# Default task: Wipes out dist and coverage directory. Compiles using babel.
gulp

Deployment

# compile to ES5
1. yarn build

# upload dist/ to your server
2. scp -rp dist/ [email protected]:/path

# install production dependencies only
3. yarn --production

# Use any process manager to start your services
4. pm2 start dist/index.js

In production you need to make sure your server is always up so you should ideally use any of the process manager recommended here. We recommend pm2 as it has several useful features like it can be configured to auto-start your services if system is rebooted.

Logging

Universal logging library winston is used for logging. It has support for multiple transports. A transport is essentially a storage device for your logs. Each instance of a winston logger can have multiple transports configured at different levels. For example, one may want error logs to be stored in a persistent remote location (like a database), but all logs output to the console or a local file. We just log to the console for simplicity, you can configure more transports as per your requirement.

API logging

Logs detailed info about each api request to console during development.

Error logging

Logs stacktrace of error to console along with other details. You should ideally store all error messages persistently.

Code Coverage

Get code coverage summary on executing yarn test

yarn test also generates HTML code coverage report in coverage/ directory. Open lcov-report/index.html to view it.

Docker

Using Docker Compose for Development

# service restarts on file change
bash bin/development.sh

Building and running without Docker Compose

# To use this option you need to make sure mongodb is listening on port 27017

# Build docker 
docker build -t express-mongoose-es6-rest-api .

# Run docker
docker run -p 4040:4040 express-mongoose-es6-rest-api

A Boilerplate-only Option

If you would prefer not to use any of our tooling, delete the following files from the project: package.json, gulpfile.babel.js, .eslintrc and .travis.yml. You can now safely use the boilerplate with an alternative build-system or no build-system at all if you choose.

Docs and Recipes

• Gulp recipes - the official Gulp recipes directory includes a comprehensive list of guides for different workflows you can add to your project.

Contributing

Contributions, questions and comments are all welcome and encouraged. For code contributions submit a pull request with unit test.

License

This project is licensed under the MIT License

Support Development

If this project saved your valuable time in getting your service up, and you feel like buying me coffee, you can donate either at my BTC address: 1LkW5UoERR1jjJsChMheKuo6vn95x2mzWg or at

Your support is greatly appreciated.

Meta

Kunal Kapadia @kunalkapadia12 [email protected]