koa-ts-full-template

This is a full project structure, integrated with ts. This project has been configured with a mysql database, support different environment(dev,prod,testing) configuration, some custom koa middleware have configured, and it has defined a unified api response format.

Features

✓ koa v2

✓ Typescript

✓ Jest

✓ APIDOC

✓ Docker

✓ Eslint

✓ Husky

✓ Unified API response

Installation CLI

 npm i -g koa-ts-cli

Create Project

 koats create myProject
 # Choose koa-ts-full-template option.
 
 cd myProject
 npm install

Environments

There are three running environment can be configured: development, testing and production. You can set NODE_ENV environment variables to select one of the mode.

 npx cross-env NODE_ENV=development npm run start

Every running environment is corresponding to a configuration file. Please see myProject/src/app/config/*.

• development: myProject/src/app/config/dev.config.ts

 npx cross-env NODE_ENV=development npm run start

or

 npm run start:dev

• test environment: myProject/src/app/config/test.config.ts

 cross-env NODE_ENV=testing npm run start

or

 npm run start:test

• production: myProject/src/app/config/prod.config.ts

 cd myProject
 npm run build

 cd myProject/dist
 npm install
 npm run prod

If the above scripts can't meet your requirements, you can customize your scripts in the package.json file.

Create Mysql DB

This project will connect to the mysql database by default, so you need to create mysql database before it is started. The db configuration information is configured in the directory of myProject/src/app/config/*.

For convenience, I have created the demo sql statements for you, please see myProject/src/app/sql/db.sql. Copy sql statements in db.sql, and executing it in your mysql database.

You can modify it according to your actual condition, such as change the database name, create a new table and so on...

Note: When start the project, you need to configure your mysql database password environment variable: DB_PASSWORD.

cross-platform:

 npx cross-env DB_PASSWORD=xxx NODE_ENV=development npm run start

The Project Entry Variables

When you start the project, you need to pass the value of environment variables to the startup scripts, such as the port number, mysql database password and so on.

If you want to know what parameters are needed, please see myProject/src/app/config/variate.ts.

This file contains all the required variables of the project.

For example:

 // DB_PASSWORD is the mysql database password
 cross-env PORT=8080 DB_PASSWORD=xxx NODE_ENV=development npm run start

Running On Different Platforms

In Windows:

 set DB_PASSWORD=xxxx
 set NODE_ENV=development
 npm run start

In Linux:

 DB_PASSWORD=xxx NODE_ENV=development npm run start

cross-platform:

 npx cross-env DB_PASSWORD=xxx NODE_ENV=development npm run start

In Development Mode

set NODE_ENV = development

The development mode is suitable for you to run in localhost. You can configure it to connect to the local mysql database. For details, please see the file: myProject/src/app/config/dev.config.ts.

 npx cross-env NODE_ENV=development PORT=8080 DB_PASSWORD=xxx npm run start

or

 npx cross-env PORT=8080 DB_PASSWORD=xxx npm run start:dev

or

For convenience, I have created the shell script for you: myProject/shell/start-dev.cmd

 cd myProject/shell
 ./start-dev.cmd

In Production Mode

set NODE_ENV = production

The prod mode is suitable for you to release the project. You can configure it to connect to the online mysql database. For details, please see the file: myProject/src/app/config/prod.config.ts.

First, you need to build the project.

 cd myProject
 npm run build

Then, run myProject/dist/src/main.js.

 cd myProject/dist
 npm install
 npx cross-env PORT=8080 DB_PASSWORD=xxx npm run prod

In Testing Mode

set NODE_ENV = testing

The testing mode is suitable for you to deploy on the beta server. You can configure it to connect to the beta mysql database. For details, please see the file: myProject/src/app/config/test.config.ts.

 npx cross-env NODE_ENV=testing PORT=8080 DB_PASSWORD=xxx npm run start

or

 npx cross-env PORT=8080 DB_PASSWORD=xxx npm run start:test

or

For convenience, I have created the shell script for you: myProject/shell/start-test.cmd

 cd myProject/shell
 ./start-test.cmd

Run In Docker

 cd myProject
 npm install
 npm run build
 sudo docker build -t koa-ts-api-server .
 sudo docker run -it --name koa-ts-api-server -p 8080:8080 -e DB_PASSWORD=xxxxxx koa-ts-api-server # DB_PASSWORD is mysql db password

or

 cd myProject
 ./docker-build.sh
 sudo docker run -it --name koa-ts-api-server -p 8080:8080 -e DB_PASSWORD=xxxxxx koa-ts-api-server # DB_PASSWORD is mysql db password

Test

Unit test can be used to ensure the quality of the code.

 npx cross-env NODE_ENV=development PORT=8080 DB_PASSWORD=xxx npm run test

or

For convenience, I have created the shell script for you: myProject/shell/test.cmd

 cd myProject/shell
 ./test.cmd

Generate Apidoc

 npm run apidoc