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 docker docker-compose entity-generation express jimp mocha multer node typeorm typescript upload-file
Last synced: 3 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: 2025-01-19T00:03:00.000Z (about 1 month ago)
- Last Synced: 2025-02-10T16:49:50.903Z (10 days ago)
- Topics: api, api-rest, apidoc, authentication, boilerplate, docker, docker-compose, entity-generation, express, jimp, mocha, multer, node, typeorm, typescript, upload-file
- Language: TypeScript
- Homepage: https://fabrik.konfer.be/typeplate/apidoc
- Size: 24 MB
- Stars: 330
- Watchers: 10
- Forks: 46
- Open Issues: 0
-
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
[](https://nodejs.org/docs/latest-v20.x/api/index.html)
[](https://www.typescriptlang.org/)
[](https://expressjs.com/)
[](https://typeorm.io/#/)
[](https://mochajs.org)
[](https://coveralls.io/github/steve-lebleu/typeplate?branch=master)
[](https://www.codefactor.io/repository/github/steve-lebleu/typeplate)
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 his [ExpressREST API boilerplate](https://github.com/danielfsousa/express-rest-boilerplate) :beer:
## > Features
- **Containerization**
- **Docker** with [Dockerfile](https://docs.docker.com/get-started/).
- **Docker compose** with [docker-compose.yml](https://docs.docker.com/compose/) with mariadb and phpmyadmin.
- **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)
- [License](#license)
## Getting started
### Prerequisites
- Git
- Node.js >= 20.18.0
- NPM >= 10.2.3
- A database engine with a dedicated database (MariaDB, MySQL, PostgreSQL, ...) or Docker
### Step 1: install
#### Local
```bash
git clone https://github.com/steve-lebleu/typeplate.git path-to/your-project-name/
cd path-to/your-project-name/
npm run init
```
#### Docker
```bash
docker compose build
```
### Step 2: setup package.json
Open the *./package.json* file and edit it with your own values.
### Step 3: 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. Use "db" with docker-compose, "localhost" otherwise.
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 4: 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 5: run
#### Local run
```bash
nodemon
```
#### Docker run
```bash
docker compose up -d
```
## 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)