nodejs-express-jwt

Express REST API Boilerplate with JWT Authentication and support for MySQL and PostgreSQL.

Compilation via Babel;
Authentication via JWT;
Routes mapping via express-routes-mapper;
Environments for development, testing, and production.

Version notice
Install & Use
Controllers
- Create a Controller
Models
- Create a Model
Policies
Services
Configs
- .env
npm scripts
License

Version notice

This project came a long way since the initial release in 2018. If you used this boilerplate before 2021, you should check a v0.x.x branch and v0 tags for the latest changes of v0.

Install and Use

Start by cloning this repository

# HTTPS
$ git clone https://github.com/MarkKhramko/nodejs-express-jwt

then use npm to

# Enter project root
$ cd nodejs-express-jwt
# Install dependencies
$ npm i
# Copy environment file 
$ cp .env.example .env
# Fill .env file
# ...
# If you want to use PostgreSQL (optional)
$ npm install -S pg pg-hstore
# Start the application (without code watcher)
$ npm start
#
# OR
#
# start development with nodemon
$ npm run dev

MySQL is supported out of the box as it is the default.

Controllers

Controllers in this boilerplate have a naming convention: ModelnameController.js and uses an object factory pattern. To use a model inside of your controller you have to require it. We use Sequelize as ORM, if you want further information read the Docs.

Folder structure

Controllers for your main API should be placed inside /api/ directory;
Controllers for HTTP requests should be placed inside /web/ directory.

Create a Controller

Example Controller for all CRUD oparations:

const Model = require('#models/Model');

model.exports = function ModelController() {
  const _create = (req, res) => {
    // body is part of a form-data
    const { value } = req.body;

    Model
      .create({
        key: value
      })
      .then((model) => {
        if(!model) {
          return res.status(400).json({ msg: 'Bad Request: Model not found' });
        }

        return res.status(200).json({ model });
      })
      .catch((err) => {
        // better save it to log file
        console.error(err);

        return res.status(500).json({ msg: 'Internal server error' });
      });
  };

  const _getAll = (req, res) => {
    Model
      .findAll()
      .then((models) => {
        if(!models){
          return res.status(400).json({ msg: 'Bad Request: Models not found' });
        }

        return res.status(200).json({ models });
      })
      .catch((err) => {
        // better save it to log file
        console.error(err);

        return res.status(500).json({ msg: 'Internal server error' });
      });
  };

  const _get = (req, res) => {
    // params is part of an url
    const { id } = req.params;

    Model
      .findOne({
        where: {
          id,
        },
      })
      .then((model) => {
        if(!model) {
          return res.status(400).json({ msg: 'Bad Request: Model not found' });
        }

        return res.status(200).json({ model });
      })
      .catch((err) => {
        // better save it to log file
        console.error(err);

        return res.status(500).json({ msg: 'Internal server error' });
      });
  };

  const _update = (req, res) => {
    // params is part of an url
    const { id } = req.params;

    // body is part of form-data
    const { value } = req.body;

    Model
      .findByPk(id)
      .then((model) => {
        if(!model) {
          return res.status(400).json({ msg: 'Bad Request: Model not found' });
        }

        return model
          .update({
            key: value,
          }).then((updatedModel) => {
            return res.status(200).json({ updatedModel });
          });
      })
      .catch((err) => {
        // better save it to log file
        console.error(err);

        return res.status(500).json({ msg: 'Internal server error' });
      });
  };

  const _destroy = (req, res) => {
    // params is part of an url
    const { id } = req.params;

    Model
      .findByPk(id)
      .then((model) => {
        if(!model) {
          return res.status(400).json({ msg: 'Bad Request: Model not found' })
        }

        model.destroy().then(() => {
          return res.status(200).json({ msg: 'Successfully destroyed model' });
        }).catch((err) => {
          // better save it to log file
          console.error(err);

          return res.status(500).json({ msg: 'Internal server error' });
        });
      })
      .catch((err) => {
        // better save it to log file
        console.error(err);

        return res.status(500).json({ msg: 'Internal server error' });
      });
  };

  // !IMPORTANT!
  // don't forget to return the functions:
  return {
    create:_create,
    getAll:_getAll,
    get:_get,
    update:_update,
    destroy:_destroy
  };
};

Models

Models in this boilerplate have a naming convention: Model.js and uses Sequelize to define Models, if you want further information read the Docs.

Create a Model

Example User Model:

const { DataTypes } = require('sequelize');
const database = require('#services/db.service');

// Password hasher.
const bcryptSevice = require('#services/bcrypt.service');


const User = database.define(
  'User',
  {
    email: {
      type: DataTypes.STRING(255),
      unique: true,
      allowNull: false
    },
    password: {
      type: DataTypes.STRING(255),
      allowNull: false
    },
  }
);

// Hooks:
User.beforeValidate((user, options) => {
  // Hash user's password.
  user.password = bcryptSevice.hashPassword(user);
})
// Hooks\

module.exports = User;

Policies

Policies are middleware functions that can run before hitting a apecific or more specified route(s).

Services

Services are little useful snippets, or calls to another API that are not the main focus of your API.

Example service:

Get comments from another API:

module.exports = {
  getComments:_getComments
};

async function _getComments() {
  try {
    const res = await fetch('https://jsonplaceholder.typicode.com/comments', {
      method: 'get'
    });
    // do some fancy stuff with the response.
  }
  catch(error) {
    // Process error.
  }
}

Configs

.env file

Database

Configure the keys with your credentials in .env file.

  DB_DIALECT=mysql
  DB_HOST=localhost
  DB_NAME=name
  DB_USER=root
  DB_PASSWORD=root
  DB_PORT=3609

Default dialect for the application is MySQL. To switch for PostgreSQL, type DB_DIALECT=postgres in .env file.

Note: if you use mysql make sure MySQL server is running on the machine

Note: to use a postgres run : npm i -S pg pg-hstore or yarn add pg pg-hstore

JWT

Set random secret access keys for your access and refresh tokens.

JWT_ACCESS_SECRET=<any random string>
JWT_REFRESH_SECRET=<any random string>

npm scripts

`npm run dev`

This is the entry for a developer. This command:

runs nodemon watch task for the all files conected to .app/app.js, except ./public directory;
Reads environment variable NODE_ENV from .env;
Opens the db connection for development;
Starts the server on 127.0.0.1:APP_PORT,

`npm run production`

This command:

Sets the environment variable to production;
Opens the db connection for production;
Starts the server on 127.0.0.1:APP_PORT.

Before running on production you have to set the environment vaiables:

APP_PORT - Port for your application (usually 80);
DB_DIALECT - mysql or postgresl;
DB_HOST - Host address of your database;
DB_NAME - Database name for production;
DB_USER - Database username for production;
DB_PASS - Database password for production;
DB_PORT - Database port for production;
JWT_ACCESS_SECRET - Secret for JSON web token for direct API requests;
JWT_REFRESH_SECRET - Secret for JSON web token to renew the Access-JWT.

`npm start`

This command:

Opens the db connection for default environment in .env file.
Simply start the server on 127.0.0.1:APP_PORT without a watcher.

`npm run db:migrate`

This command:

Ensures that database schemas are equivalent to the ones configured in /app/models/index.js.

`npm run db:seed`

This command:

Inserts all seeds, configured in /migrator/seeder.js into the database.

LICENSE

MIT 2018-present. By Mark Khramko

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

MarkKhramko / nodejs-express-jwt

Programming Languages

Labels

Projects that are alternatives of or similar to nodejs-express-jwt

nodejs-express-jwt

Table of Contents

Version notice

Install and Use

Controllers

Folder structure

Create a Controller

Models

Create a Model

Policies

Services

Configs

.env file

Database

JWT

npm scripts

`npm run dev`

`npm run production`

`npm start`

`npm run db:migrate`

`npm run db:seed`

LICENSE