README.md

Ready to use RESTful API boilerplate builded with Express.js, Typescript TypeORM and Mocha. 🤘

Thanks to Daniel F. Sousa for inspiration with her Express ES2017 REST API boilerplate 🍺

> Features

• Basics
  • Clear & clean code architecture with classic layers such controllers, services, repositories, models, ...
  • Object Relational Mapping with typeorm.
  • Entity generation with rsgen.
  • Business validation with self designed business members.
  • Logs management with morgan and winston.
  • Changelog completion with auto-changelog.
  • Testing with included unit and integration test sets builded with mocha, chai, sinon and supertest.
  • Documentation with api-doc.
• Security
  • SSL secure connection with native HTTPS node module.
  • Cross Origin Resource Sharing with CORS.
  • Securized HTTP headers with helmet.
  • HTTP header pollution preventing with hpp.
  • API request rate limit with express-rate-limit.
  • Route validation with joi.
  • HTTP friendly errors with boom and http-status.
• Authentication
  • JWT authentication process with passport.js.
  • oAuth authentication process with passport.js.
  • Sending transactional emails with cliam.
• Performances
  • HTTP request cache with memory-cache.
  • Database query cache with typeorm caching.
• Assets management
  • Customizable file upload with multer.
  • Customizable image resizing with jimp.

> Table of contents

• Getting started
• Entity generation
• Documentation
• Tests
• Continuous integration
• Deployment
• Licence

Getting started

Prerequisites

• Git
• Node.js >= 14.16.0
• NPM >= 6.14.0
• A database engine with a dedicated database

When you're with that, starting your project is a matter of minutes. 🕛

Step 1: install

$ git clone https://github.com/konfer-be/typeplate.git path-to/your-project-name/

Step 2: go to

$ cd path-to/your-project-name/

Step 3: build

$ npm run init

Step 4: setup package.json

Open the ./package.json file and edit it with your own values.

Step 5: setup environment

Open ./dist/env/development.env and fill the required env variables (uncommented in the file). See wiki env variables list for more informations.

# Access token Secret passphrase
ACCESS_TOKEN_SECRET = "your-secret"

# CORS authorized domains
AUTHORIZED = "http://localhost:4200"

# API domain
DOMAIN = "localhost"

# Application port.
PORT = 8101

# Refresh token Secret passphrase
REFRESH_TOKEN_SECRET = "your-secret"

# Database engine
TYPEORM_TYPE = "mysql"

# Database server host
TYPEORM_HOST = "localhost"

# Database name. Keep it different from your developement database.
TYPEORM_DB = "your-database"

# Database user
TYPEORM_USER = "root"

# Database password
TYPEORM_PWD = ""

# Database port
TYPEORM_PORT = "3306"

Step 6: setup cliamrc.js

Transactional emails are send with cliam. Open the .cliamrc.js and fill the required configuration according your sending mode. See Cliam official documentation for more information.

Sandbox is set to true by default.

Step 7: run

$ nodemon

Entity generation

Some repetitive tasks such as creating resources can be done quickly with rsgen.

See entity generation wiki section to learn more about generated elements and how to use.

Documentation

$ npm run doc

Generate API documentation website into ./docs/apidoc/.

See apidoc for more informations about customization.

Tests

$ npm run test

⚠️ Because there are integration tests, you need a dedicated database to run the tests suites. It's already managed in CI/CD using Github actions, You need to mount it yourself in your local environment.

HTML coverage report is generated by Istanbul in ./reports/nyc-coverage.

Bonus with ./insomnia.workspace.json if you wish run manual e2e tests without create the config.

Continuous integration

Basic Github actions configuration is provided in ./.github/workkflows.yml files.

Deployment

Project implements a basic PM2 configuration to allow deployment.

Install PM2 globaly :

$ npm i pm2 -g

Configuration

Configure the ./ecosystem.config.js file with your env informations.

{
  deploy : {
    staging : {
        user : 'node',
        host : '212.83.163.1',
        ref  : 'origin/master',
        repo : '[email protected]:repo.git',
        ssh_options: ['StrictHostKeyChecking=no', 'PasswordAuthentication=yes', 'ForwardAgent=yes'],
        path : '/var/www/staging',
          'post-setup' : 'npm run kickstart:staging && pm2 reload ecosystem.config.js --env staging',
          'post-deploy' : 'npm i && tsc && pm2 reload ecosystem.config.js --env staging'
      }
  }
}

More info about PM2 ecosystem.config.js file.

Deploy

Pm 2 must be installed on the target server and your SSH public key granted.

# Setup deployment at remote location
$ pm2 deploy production setup

# Update remote version
$ pm2 deploy production update

More info about PM2 and PM2 deploy.

License

MIT