{"id":13710194,"url":"https://github.com/steve-lebleu/typeplate","last_synced_at":"2025-10-26T10:33:05.924Z","repository":{"id":40705603,"uuid":"204288916","full_name":"steve-lebleu/typeplate","owner":"steve-lebleu","description":"REST API boilerplate with Typescript, Express.js, Typeorm and Mocha.","archived":false,"fork":false,"pushed_at":"2025-03-10T22:30:53.000Z","size":25422,"stargazers_count":335,"open_issues_count":2,"forks_count":46,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-09T04:03:23.618Z","etag":null,"topics":["api","api-rest","apidoc","authentication","boilerplate","docker","docker-compose","entity-generation","express","jimp","mocha","multer","node","typeorm","typescript","upload-file"],"latest_commit_sha":null,"homepage":"https://fabrik.konfer.be/typeplate/apidoc","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/steve-lebleu.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":"stevelebleu","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2019-08-25T12:07:35.000Z","updated_at":"2025-04-04T13:26:24.000Z","dependencies_parsed_at":"2024-01-04T20:27:34.752Z","dependency_job_id":"bdbdea42-a59e-4885-b025-b0281a342d04","html_url":"https://github.com/steve-lebleu/typeplate","commit_stats":null,"previous_names":["steve-lebleu/typeplate","konfer-be/typeplate"],"tags_count":65,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steve-lebleu%2Ftypeplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steve-lebleu%2Ftypeplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steve-lebleu%2Ftypeplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steve-lebleu%2Ftypeplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/steve-lebleu","download_url":"https://codeload.github.com/steve-lebleu/typeplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254501557,"owners_count":22081528,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-rest","apidoc","authentication","boilerplate","docker","docker-compose","entity-generation","express","jimp","mocha","multer","node","typeorm","typescript","upload-file"],"created_at":"2024-08-02T23:00:52.940Z","updated_at":"2025-10-26T10:33:00.892Z","avatar_url":"https://github.com/steve-lebleu.png","language":"TypeScript","funding_links":["https://ko-fi.com/stevelebleu"],"categories":["TypeScript"],"sub_categories":[],"readme":"![Typescript / Express / Typeorm REST API boilerplate](https://i.ibb.co/dM2bhNJ/cover-typeplate.png)\n\n[![Node](https://img.shields.io/badge/Node-20.18.0-informational?logo=node.js\u0026color=43853D)](https://nodejs.org/docs/latest-v20.x/api/index.html)\n[![TypeScript](https://img.shields.io/badge/Typescript-5.7.2-informational?logo=typescript\u0026color=2F74C0)](https://www.typescriptlang.org/)\n[![Express](https://img.shields.io/badge/Express-4.21.2-informational?logo=express\u0026color=B1B1B1)](https://expressjs.com/)\n[![Typeorm](https://img.shields.io/badge/Typeorm-0.3.20-informational?logo=typeorm\u0026color=FFAB00)](https://typeorm.io/#/)\n[![Mocha](https://img.shields.io/badge/Mocha-10.3.0-informational?logo=mocha\u0026color=8A6343)](https://mochajs.org)\n\n![Github action workflow status](https://github.com/steve-lebleu/typeplate/actions/workflows/build.yml/badge.svg?branch=master)\n[![Coverage Status](https://coveralls.io/repos/github/steve-lebleu/typeplate/badge.svg?branch=master)](https://coveralls.io/github/steve-lebleu/typeplate?branch=master)\n[![CodeFactor](https://www.codefactor.io/repository/github/steve-lebleu/typeplate/badge)](https://www.codefactor.io/repository/github/steve-lebleu/typeplate)\n![GitHub Release](https://img.shields.io/github/v/release/steve-lebleu/typeplate?logo=Github)\n![GitHub License](https://img.shields.io/github/license/steve-lebleu/typeplate?color=%230A7BBC)\n\nReady 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/). 🤘\n\nThanks to Daniel F. Sousa for inspiration with his [ExpressREST API boilerplate](https://github.com/danielfsousa/express-rest-boilerplate) :beer:\n\n## \u003e Features\n\n- **Containerization**\n  - **Docker** with [Dockerfile](https://docs.docker.com/get-started/).\n  - **Docker compose** with [docker-compose.yml](https://docs.docker.com/compose/) with mariadb and phpmyadmin.\n- **Basics**\n  - **Clear \u0026 clean code architecture** with classic layers such controllers, services, repositories, models, ...\n  - **Object Relational Mapping** with [typeorm](https://typeorm.io/#/).\n  - **Entity generation** with [rsgen](https://github.com/steve-lebleu/rsgen).\n  - **Business validation** with self designed business members.\n  - **Logs management** with [morgan](https://github.com/expressjs/morgan) and [winston](https://github.com/winstonjs/winston).\n  - **Changelog completion** with [auto-changelog](https://www.npmjs.com/package/auto-changelog).\n  - **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).\n  - **Documentation** with [api-doc](https://apidocjs.com/).\n- **Security**\n  - **SSL secure connection** with native [HTTPS node module](https://nodejs.org/docs/latest-v14.x/api/https.html).\n  - **Cross Origin Resource Sharing** with [CORS](https://expressjs.com/en/resources/middleware/cors.html).\n  - **Securized HTTP headers** with [helmet](https://helmetjs.github.io/).\n  - **HTTP header pollution** preventing with [hpp](https://www.npmjs.com/package/hpp).\n  - **API request rate limit** with [express-rate-limit](https://www.npmjs.com/package/express-rate-limit).\n  - **Route validation** with [joi](https://github.com/hapijs/joi).\n  - **HTTP friendly errors** with [boom](https://github.com/hapijs/boom) and [http-status](https://www.npmjs.com/package/http-status).\n- **Authentication**\n  - **JWT authentication process** with [passport.js](http://www.passportjs.org/).\n  - **oAuth authentication process** with [passport.js](http://www.passportjs.org/). \n  - **Sending transactional emails** with [cliam](https://github.com/steve-lebleu/cliam).\n- **Performances**\n  - **HTTP request cache** with [memory-cache](https://www.npmjs.com/package/memory-cache).\n  - **Database query cache** with [typeorm caching](https://github.com/typeorm/typeorm/blob/master/docs/caching.md).\n- **Assets management**\n  - **Customizable file upload** with [multer](https://www.npmjs.com/package/multer).\n  - **Customizable image resizing** with [jimp](https://www.npmjs.com/package/jimp).\n\n## \u003e Table of contents\n\n- [Getting started](#getting-started)\n- [Entity generation](#entity-generation)\n- [Documentation](#documentation)\n- [Tests](#tests)\n- [Continuous integration](#continuous-integration)\n- [Deployment](#deployment)\n- [License](#license)\n\n## Getting started\n\n### Prerequisites\n\n- Git\n- Node.js \u003e= 20.18.0\n- NPM \u003e= 10.2.3\n- A database engine with a dedicated database (MariaDB, MySQL, PostgreSQL, ...) or Docker\n\n### Step 1: install\n\n#### Local\n\n```bash\ngit clone https://github.com/steve-lebleu/typeplate.git path-to/your-project-name/\ncd path-to/your-project-name/\nnpm run init\n```\n\n#### Docker\n\n```bash\ndocker compose build\n```\n\n### Step 2: setup package.json\n\nOpen the *./package.json* file and edit it with your own values.\n\n### Step 3: setup environment\n\nOpen *./dist/env/development.env* and fill the required env variables (uncommented in the file).\n\nSee wiki [env variables list](https://github.com/steve-lebleu/typeplate/wiki/Environment-variables) for more informations.\n\n```bash\n# Access token Secret passphrase\nACCESS_TOKEN_SECRET = \"your-secret\"\n\n# CORS authorized domains\nAUTHORIZED = \"http://localhost:4200\"\n\n# API domain\nDOMAIN = \"localhost\"\n\n# Application port.\nPORT = 8101\n\n# Refresh token Secret passphrase\nREFRESH_TOKEN_SECRET = \"your-secret\"\n\n# Database engine\nTYPEORM_TYPE = \"mysql\"\n\n# Database server host. Use \"db\" with docker-compose, \"localhost\" otherwise.\nTYPEORM_HOST = \"localhost\"\n\n# Database name. Keep it different from your developement database.\nTYPEORM_DB = \"your-database\"\n\n# Database user\nTYPEORM_USER = \"root\"\n\n# Database password\nTYPEORM_PWD = \"\"\n\n# Database port\nTYPEORM_PORT = \"3306\"\n```\n\n### Step 4: setup cliamrc.js\n\nTransactional 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.\n\nSandbox is set to true by default.\n\n### Step 5: run\n\n#### Local run\n\n```bash\nnodemon\n```\n\n#### Docker run\n\n```bash\ndocker compose up -d\n```\n\n## Entity generation\n\nSome repetitive tasks such as creating resources can be done quickly with [rsgen](https://github.com/steve-lebleu/rsgen).\n\nSee [entity generation](https://github.com/steve-lebleu/typeplate/wiki/Entity-generation) wiki section to learn more about generated elements and how to use.\n\n## Documentation\n\n```bash\nnpm run doc\n```\n\nGenerate API documentation website into *./docs/apidoc/*.\n\nSee [apidoc](http://apidocjs.com/) for more informations about customization.\n\n## Tests\n\n```bash\nnpm run test\n```\n\n: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.\n\nHTML coverage report is generated by [Istanbul](https://github.com/gotwarlost/istanbul) in *./reports/nyc-coverage*.\n\nBonus with *./insomnia.workspace.json* if you wish run manual e2e tests without create the config.\n\n## Continuous integration\n\nBasic Github actions configuration is provided in *./.github/workkflows.yml* files.\n\n## Deployment\n\nProject implements a basic [PM2](https://github.com/Unitech/PM2/) configuration to allow deployment.\n\nInstall PM2 globaly :\n\n```bash\nnpm i pm2 -g\n```\n\n### Configuration\n\nConfigure the *./ecosystem.config.js* file with your env informations.\n\n```javascript\n{\n  deploy : {\n    staging : {\n        user : 'node',\n        host : '212.83.163.1',\n        ref  : 'origin/master',\n        repo : 'git@github.com:repo.git',\n        ssh_options: ['StrictHostKeyChecking=no', 'PasswordAuthentication=yes', 'ForwardAgent=yes'],\n        path : '/var/www/staging',\n          'post-setup' : 'npm run kickstart:staging \u0026\u0026 pm2 reload ecosystem.config.js --env staging',\n          'post-deploy' : 'npm i \u0026\u0026 tsc \u0026\u0026 pm2 reload ecosystem.config.js --env staging'\n      }\n  }\n}\n```\n\nMore info about PM2 [ecosystem.config.js](https://pm2.io/doc/en/runtime/reference/ecosystem-file/) file.\n\n### Deploy\n\nPm 2 must be installed on the target server and your SSH public key granted.\n\n```bash\n# Setup deployment at remote location\npm2 deploy production setup\n\n# Update remote version\npm2 deploy production update\n```\n\nMore 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/).\n\n## License\n\n[MIT](/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteve-lebleu%2Ftypeplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteve-lebleu%2Ftypeplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteve-lebleu%2Ftypeplate/lists"}