express-template

An opinionated template for an Express based project, featuring a standardized structure, containerization, authentication, ORM, development utilities, etc.

Getting Started

• Features
• Setup Project
• Architecture Overview

Features

Main Features

• REST API template Web Application
  • Express - Express is a minimal and flexible Node.js web application framework that provides a robust set of features to develop an api.
• JWT Authentication
  • Passport - Passport is authentication middleware for Node.js. Easy to integrate in an Express-based web application.
• Database Connection w/ ORM and GUI
  • PostgreSQL - PostgreSQL is a powerful, open source object-relational database system with over 30 years of active development that has earned it a strong reputation for reliability, feature robustness, and performance.
  • Sequelize - Sequelize is a promise-based Node.js ORM for Postgres, MySQL, MariaDB, SQLite and Microsoft SQL Server. It features solid transaction support, relations, eager and lazy loading, read replication and more.
  • pgAdmin - pgAdmin is the most popular and feature rich Open Source administration and development platform for PostgreSQL.
• Containerization
  • Docker - Docker containers wrap up software and its dependencies into a standardized unit for software development that includes everything it needs to run: code, runtime, system tools and libraries.
  • (Docker) Compose - Compose is a tool for defining and running multi-container Docker applications. We use Compose to run a Web Application, the postgreSQL database and the pgAdmin instance to interact with the database.

Development Features

• Unit Tests Template w/ Coverage
  • Chai - Chai is a BDD/TDD assertion library for Node.js and the browser that can be paired with any Javascript testing framework. We use the Should style.
  • Mocha - Mocha is a JavaScript test framework running on Node.js and in the browser, making asynchronous simple.
  • nyc(Instabul's cli-client) - Istanbul is a test coverage tool for ES5 and ES2015+ Javascript.
• Linting
  • ESLint - Tool for identifying and reporting on patterns found in ECMAScript/JavaScript code. We enforce the Airbnb style.
• Hot Reloading
  • nodemon - Nodemon is a utility that will monitor for any changes in your source and automatically restart your server.

Setup Project

• Cloning Project
• Prerequisites
• Run Containers
• Setup pgAdmin
• Running Tests
• Running Linter

Cloning Project

$ git clone https://github.com/diogotorres97/express-template
$ cd express-template

Prerequisites

To use the template, you need the following software installed (official instructions linked):

• Docker
• (Docker) Compose

Note: If you're using Linux, you might enconter permission errors while installing Docker. Try this.

Run Containers

Inside the repository's main directory, run:

$ docker-compose up

You should now be able to access:

• http://localhost:3000 - REST API instance
• http://localhost:5050 - pgAdmin instance

Setup pgAdmin

When you access the pgAdmin instance for the first time, there will be no server connection. You must create one. When doing so, consult the docker-compose file (docker-compose.yml) to check the database configuration. An example connection creation:

Tip: In pgAdmin, you can find the server's schemas at Servers/<server-name>/Databases/<Maintenance-database-name>/Schemas/public/Tables.

Running Tests

 $ chmod +x test.sh # set executable permissions
 $ sh test.sh

Running Linter

$ cd server
$ docker-compose run template-server sh
$ npm run lint # run linter
$ npm run lint:fix # run linter and fix errors

Architecture Overview

Repository structure

express-template/
\-- server
|   \-- src
|   |   \-- config
|   |   \-- controllers
|   |   \-- migrations
|   |   \-- models
|   |   \-- routes
|   |   \-- seeders
|   |   \-- services
|   |   \-- test
|   |   \-- utils
|   +-- Dockerfile
|   +-- package.json

Main Sections Overview

Section	Description
Config	Definition of global variables independent to the application's context. Relevant for the setup of CI / CD.
Models	The models defined through ORM, hence representing the database schema.
Controllers	Handlers responsible for the manipulation of the respective Models.
Migrations	Migrations are like version control for your database, allowing your team to easily modify and share the application's database schema.
Routes	Where the mapping between the Controllers' functions and the actual URL endpoints are made.
Seeders	Definition of an initial set of values used to populate the database.
Services	Additional services such as OAuth, email integration, websockets, among others.
Test	Definition of a set of files with the purpose of verifying that our server is working as it is supposed to.
Utils	Definition of a set of utility functions that can be used across all afore-mentioned sections

Other important files:

File	Description
Dockerfile	Text document that contains all the commands used to support the express framework. It's based on node:11-alpine and has some dependencies installed to support the bcrypt package.
package.json	JSON document that describes the behavior of the related npm-package. Defines some useful scripts used in this template but also the dependencies installed as well as their version.

Detailed View of Important Sections

Models

This template uses Sequelize, promise-based ORM for Node.js. It supports the dialects PostgreSQL, MySQL, MariaDB, SQLite, and MSSQL and features solid transaction support, relations, read replication and more. In this case, we use it with PostgreSQL.

When trying to define your models, it might be useful to check some of the Sequelize documentation, such as the Datatypes or the Associations.