konfer-be/typeplate

REST API boilerplate with Typescript, Express.js, Typeorm and Mocha.

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

typeplate's Issues

Generate initial db

Hi,

how can i generate initial database with typeorm cli sync or migration?

migration gave me "No changes in database schema were found - cannot generate a migration."
and scheme:sync "Schema syncronization finished successfully."

May be i'm do something wrong.

understood that question is semi related to your project, but hope that you can push my searches in right direction.

Thank you.

whitelist issue

When we have boolean type of value in entity whitelist ,it is returning as blank object like this {} due to sanitize method.

How does the get user by id work?

First of all.. thanks for this awesome project. I have been using it to get a handle on typescript en typeorm. I really don't have an issue with this project, it works perfectly fine. I just don't get how the 'get' method works for getting a user by it's id.

It does not seem to use the 'one' method from the 'UserRepository'.

Would it be possible to get an explanation?

Sanitizer is not working for response

Hi

whenever i call the login API, i get the full data. the whitelist filter is not working for sanitizing the data. Can you please let me know if there is anything missing in the setup or its a legit issue.

{
"token": {
"tokenType": "Bearer",
"accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MjI4MTYxOTMsImlhdCI6MTYxNTU1ODU5Mywic3ViIjoxfQ.8FQyaJyuj_CbAOOpiMKpEYLTkwOC8mEYW94w3l17wqE",
"refreshToken": "1.0ed40da504b505a5d1ceca31bdd0765e77fc905d7721345a6d060bb9827de7d72eb83a14d51809ca",
"expiresIn": "2021-06-04T14:16:33.809Z"
},
"user": {
"id": 1,
"username": "john-doe",
"email": "[email protected]",
"password": "$2b$10$bW42twvRzce3WtiR926D0OIBgjoiHE0sb32dScN1JV36GEtcQLj2S",
"apikey": "[email protected]",
"role": "user",
"createdAt": "2021-03-12T16:17:01.410Z",
"updatedAt": null,
"deletedAt": null,
"medias": [],
"temporaryPassword": "$2b$10$bW42twvRzce3WtiR926D0OIBgjoiHE0sb32dScN1JV36GEtcQLj2S"
}
}

best regards,
Mizan

Update TypeORM version

Breaking change

Error Starting Project

Hello i have some trouble on starting project.
i used
nodemon ./src/api/app.bootstrap.ts

but i have this error:
Cannot find module '@servers/mysql.server'

can you help me to start the project ?