Koa Boilerplate 🚀

Koa + Typescript + TypeORM codebase containing real world examples (CRUD, auth, advanced patterns, etc) that adheres to the RealWorld spec and API.

Features

• ✔️ Strict Typescript Configuration
• 🧬 TypeORM For ORM And Migration Configuration
• 💉 Awilix-Koa For Dependancy Injection And Declarative Routing
• 🐋 Dockerized For Easy Deployments
• 💯 100% Unit Test Coverage with Jest And Sinon
• 🧪 Integration Test Configuration using Docker-Compose, Jest and SuperTest
• 🚚 CI/CD Pipelines With Travis
• 🔒 JWT Auth and Password Hashing
• 📜 Environment Specific With Dotenv
• ⛔ Joi For Request Validation
• 🎀 Cleaner Code With ESLint And Prettier
• 🧭 Realworld Example Implementation
• 💣 Ejection script to remove example code

Coming Soon

• 🛵 Generator scripts to add controllers, middleware and services with tests
• 🧪 More integration test coverage

Table of Contents

• Prerequisites
• Local Setup
• Ejection
• Commands
• External Docs
• Project Structure
• License

Prerequisites

• Node v12+
• Postgres v10+
• Docker

Local

1. Clone and Install

   git clone <url>
   
   cd koa-boilerplate
   
   npm install
   
   npm run build

2. Environment and DB setup

   Add a .env file in the root of the directory with the following environment variables. Change connection URL as needed for your local postgres install

   NODE_ENV=development
   PORT=3000
   SECRET=foobar
   TYPEORM_CONNECTION=postgres
   TYPEORM_URL=postgres://postgres:Password1@localhost:5432/postgres
   TYPEORM_ENTITIES=build/src/entities/*.js
   TYPEORM_MIGRATIONS=build/migrations/*.js
   TYPEORM_MIGRATIONS_TABLE_NAME=migrations
   TYPEORM_MIGRATIONS_DIR=migrations

   Run migrations using typeorm

   npx typeorm migration:run

3. Run locally

   Start app locally to verify connection

   npm run start:dev

4. Test your local setup works

   This should finish successfully to know you have a working local setup and any changes you have made are not breaking

   npm run commit

   Runs:

   • Build
   • Linting
   • Unit Tests
   • Docker Build
   • Integration Tests

Ejection

npm run eject

Removes the Realworld Example Code, Updates the Initial Migration while maintaining full code coverage

Commands

1. npm scripts

   npm run <command>

   • start:dev Run typescript files directly using nodemon and tsnode. Detects changes and automatically restarts server
   • build Runs tsc to compile the app. Files are emitted to /build.
   • eject Removes example code
   • lint Checks for linting errors using ESLint configuration
   • unittest Run jest unittests with code coverage
   • unittest:watch Detects changes and automatically re-runs tests
   • docker:up Standup the dockerize app, a postgres docker image and a migration image that migrates the db
   • docker:down Teardown the docker containers
   • inttest Run integration tests against the docker images
   • inttest:watch Run integration tests and watch for changes
   • commit Runs the previouse commands to verify changes before commit. This command also runs in the pipeline

2. typeorm scripts

   All TypeORM commands run on the configuration information specified in the .env folder. See TypeORM CLI Docs

   npx typeorm <command>

   • migration:run Apply any reminaing migrations to the db specified in
   • migration:revert Revert the most recent migration applied
   • migration:show Show all migrations with status
   • migration:generate -n migrationNameHere Compare entities to current db schema and generate migration with changes
   • migration:create -n migrationNameHere Create a new migration

Docs

• Koa
• Typescript
• TypeORM
• Awilix-Koa
• Docker
• Hapi/Joi
• EsLint
• Sinon
• Supertest

Structure

• Coming Soon...

License

• MIT license
• Copyright 2020 © Evan Gordon Fleming.