Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/steve-lebleu/typeplate
REST API boilerplate with Typescript, Express.js, Typeorm and Mocha.
https://github.com/steve-lebleu/typeplate
api api-rest apidoc authentication boilerplate e2e-tests entity-generation express mocha node typedoc typeorm typescript upload-file
Last synced: 7 days ago
JSON representation
REST API boilerplate with Typescript, Express.js, Typeorm and Mocha.
- Host: GitHub
- URL: https://github.com/steve-lebleu/typeplate
- Owner: steve-lebleu
- License: mit
- Created: 2019-08-25T12:07:35.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-06-16T09:58:51.000Z (7 months ago)
- Last Synced: 2024-12-29T15:09:36.848Z (14 days ago)
- Topics: api, api-rest, apidoc, authentication, boilerplate, e2e-tests, entity-generation, express, mocha, node, typedoc, typeorm, typescript, upload-file
- Language: TypeScript
- Homepage: https://fabrik.konfer.be/typeplate/apidoc
- Size: 24.6 MB
- Stars: 329
- Watchers: 10
- Forks: 46
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome - steve-lebleu/typeplate - REST API boilerplate with Typescript, Express.js, Typeorm and Mocha. (TypeScript)
README
![Typescript / Express / Typeorm REST API boilerplate](https://i.ibb.co/tbqXm9Q/header-ts-boilerplate-4.png)
[![Node](https://img.shields.io/badge/Node-18.19.0-informational?logo=node.js&color=43853D)](https://nodejs.org/docs/latest-v18.x/api/index.html)
[![TypeScript](https://img.shields.io/badge/Typescript-5.3.3-informational?logo=typescript&color=2F74C0)](https://www.typescriptlang.org/)
[![Express](https://img.shields.io/badge/Express-4.18.2-informational?logo=express&color=B1B1B1)](https://expressjs.com/)
[![Typeorm](https://img.shields.io/badge/Typeorm-0.3.20-informational?logo=typeorm&color=FFAB00)](https://typeorm.io/#/)
[![Mocha](https://img.shields.io/badge/Mocha-10.3.0-informational?logo=mocha&color=8A6343)](https://mochajs.org)![Github action workflow status](https://github.com/steve-lebleu/typeplate/actions/workflows/build.yml/badge.svg?branch=master)
[![Coverage Status](https://coveralls.io/repos/github/steve-lebleu/typeplate/badge.svg?branch=master)](https://coveralls.io/github/steve-lebleu/typeplate?branch=master)
[![CodeFactor](https://www.codefactor.io/repository/github/steve-lebleu/typeplate/badge)](https://www.codefactor.io/repository/github/steve-lebleu/typeplate)
![GitHub Release](https://img.shields.io/github/v/release/steve-lebleu/typeplate?logo=Github)
![GitHub License](https://img.shields.io/github/license/steve-lebleu/typeplate?color=%230A7BBC)Ready to use RESTful API boilerplate builded with [Express.js](http://expressjs.com/en/4x/api.html), [Typescript](https://github.com/Microsoft/TypeScript) [TypeORM](https://github.com/typeorm/typeorm) and [Mocha](https://mochajs.org/). 🤘
Thanks to Daniel F. Sousa for inspiration with her [Express ES2017 REST API boilerplate](https://github.com/danielfsousa/express-rest-boilerplate) :beer:
## > Features
- **Basics**
- **Clear & clean code architecture** with classic layers such controllers, services, repositories, models, ...
- **Object Relational Mapping** with [typeorm](https://typeorm.io/#/).
- **Entity generation** with [rsgen](https://github.com/steve-lebleu/rsgen).
- **Business validation** with self designed business members.
- **Logs management** with [morgan](https://github.com/expressjs/morgan) and [winston](https://github.com/winstonjs/winston).
- **Changelog completion** with [auto-changelog](https://www.npmjs.com/package/auto-changelog).
- **Testing** with included unit and integration test sets builded with [mocha](https://mochajs.org/), [chai](https://www.chaijs.com/), [sinon](https://sinonjs.org/) and [supertest](https://github.com/visionmedia/supertest).
- **Documentation** with [api-doc](https://apidocjs.com/).
- **Security**
- **SSL secure connection** with native [HTTPS node module](https://nodejs.org/docs/latest-v14.x/api/https.html).
- **Cross Origin Resource Sharing** with [CORS](https://expressjs.com/en/resources/middleware/cors.html).
- **Securized HTTP headers** with [helmet](https://helmetjs.github.io/).
- **HTTP header pollution** preventing with [hpp](https://www.npmjs.com/package/hpp).
- **API request rate limit** with [express-rate-limit](https://www.npmjs.com/package/express-rate-limit).
- **Route validation** with [joi](https://github.com/hapijs/joi).
- **HTTP friendly errors** with [boom](https://github.com/hapijs/boom) and [http-status](https://www.npmjs.com/package/http-status).
- **Authentication**
- **JWT authentication process** with [passport.js](http://www.passportjs.org/).
- **oAuth authentication process** with [passport.js](http://www.passportjs.org/).
- **Sending transactional emails** with [cliam](https://github.com/steve-lebleu/cliam).
- **Performances**
- **HTTP request cache** with [memory-cache](https://www.npmjs.com/package/memory-cache).
- **Database query cache** with [typeorm caching](https://github.com/typeorm/typeorm/blob/master/docs/caching.md).
- **Assets management**
- **Customizable file upload** with [multer](https://www.npmjs.com/package/multer).
- **Customizable image resizing** with [jimp](https://www.npmjs.com/package/jimp).## > Table of contents
* [Getting started](#getting-started)
* [Entity generation](#entity-generation)
* [Documentation](#documentation)
* [Tests](#tests)
* [Continuous integration](#continuous-integration)
* [Deployment](#deployment)
* [Licence](#licence)## Getting started
### Prerequisites
* Git
* Node.js >= 14.16.0
* NPM >= 6.14.0
* A database engine with a dedicated databaseWhen you're with that, starting your project is a matter of minutes. :clock12:
### Step 1: install
```bash
$ git clone https://github.com/konfer-be/typeplate.git path-to/your-project-name/
```### Step 2: go to
```bash
$ cd path-to/your-project-name/
```### Step 3: build
```bash
$ 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](https://github.com/steve-lebleu/typeplate/wiki/Environment-variables) for more informations.
```bash
# 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](https://github.com/steve-lebleu/cliam). Open the *.cliamrc.js* and fill the [required configuration](https://github.com/steve-lebleu/cliam/wiki/Configuration-with-cliamrc.js) according your sending mode. See Cliam official [documentation](https://github.com/steve-lebleu/cliam/wiki) for more information.
Sandbox is set to true by default.
### Step 7: run
```bash
$ nodemon
```## Entity generation
Some repetitive tasks such as creating resources can be done quickly with [rsgen](https://github.com/steve-lebleu/rsgen).
See [entity generation](https://github.com/steve-lebleu/typeplate/wiki/Entity-generation) wiki section to learn more about generated elements and how to use.
## Documentation
```bash
$ npm run doc
```Generate API documentation website into *./docs/apidoc/*.
See [apidoc](http://apidocjs.com/) for more informations about customization.
## Tests
```bash
$ npm run test
```:warning: 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](https://github.com/gotwarlost/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](https://github.com/Unitech/PM2/) configuration to allow deployment.
Install PM2 globaly :
```bash
$ npm i pm2 -g
```### Configuration
Configure the *./ecosystem.config.js* file with your env informations.
```javascript
{
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](https://pm2.io/doc/en/runtime/reference/ecosystem-file/) file.### Deploy
Pm 2 must be installed on the target server and your SSH public key granted.
```bash
# Setup deployment at remote location
$ pm2 deploy production setup# Update remote version
$ pm2 deploy production update
```More info about [PM2](http://pm2.keymetrics.io/docs/usage/quick-start/) and [PM2 deploy](https://pm2.io/doc/en/runtime/guide/easy-deploy-with-ssh/).
## License
[MIT](/LICENSE)