nhtua / koa-starter-kit

Koa Starter Kit is a basic boilerplate for the quick starting with Koa2

Koa Starter Kit

Koa Starter Kit (KSK) is a basic boilerplate for the quick starting with Koa2. It was written in ES6 with a little messily primitive Javascript syntax that helps you get started building NodeJS API easier than ever.

KSK includes some lovely common setup:

• src structure based-on Javascript modules
• Watching file changes then reload the server
• Build production with Babel
• Routing, multi routers
• Middlewares
• CORS accepts request from domain white list
• Authentication with JSON Web Token
• Authorization with built-in solution

want more? Folk and submit your regular tasks.

Requirement

KSK requires Node >= 8.6 or higher.

Getting Started

First we'll clone source code from GitHub Repo

  git clone https://github.com/nhtua/koa-starter-kit.git

Then we need to install the dependencies

cd koa-starter-kit
npm install

Next, make your own environmental config file:

cp src/config/development.example.json src/config/development.json

Finally, run the serve

npm start

Dev's shortcuts

There are npm commands for dev's stuff.

• Run the server during the development

npm start

• Build and transpile code into Javascript for production

npm run build

• Run server as production (run the Js transpiled code)

npm run serve

• Do the UnitTest

npm run test

The REST Api

KSK has three api endpoints for demonstration purpose.

You need to setup domains white list before you can use any api endpoints in React, Angular or Vuejs application. You'll find the white list at: src/config/index.js (someone please help me turn the config file into multi enviroments config!)

/login

Login to get the jwt token.

• request config:

  • Method: POST
  • Header:

  Content-Type : application/json
  

• input: JSON as Raw body

  {
    "username": "john_doe",
    "password": "123456"
  }

• output:

{
    "error": false,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJqb2huX2RvZSIsInN0YXR1cyI6MSwidXBkYXRlZF9hdCI6IjIwMTctMDgtMzEgMDA6MDA6MDAiLCJpYXQiOjE1MDQyMDA2Mzd9.lVRnRCNB7-5zeq_DKtw0jzn_reTCKK5sYC3csIo-Je4",
    "user": {
        "id": 1,
        "username": "john_doe",
        "password": "$2a$10$TjZ4eIUYrxpF1IZ2zzU8Sel5BH6jFmdZey0L.Bmftw5apgd44hiHu",
        "email": "[e-mail]",
        "permission": 7,
        "status": 1,
        "updated_at": "2017-08-31 00:00:00",
        "created_at": "2017-08-31 00:00:00"
    },
    "message": "Logged in successfully!"
}

/user

Get user list

• request config:

  • Method: GET
  • Header:

  Content-Type : application/json
  Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJqb2huX2RvZSIsInN0YXR1cyI6MSwidXBkYXRlZF9hdCI6IjIwMTctMDgtMzEgMDA6MDA6MDAiLCJpYXQiOjE1MDQyMDA2Mzd9.lVRnRCNB7-5zeq_DKtw0jzn_reTCKK5sYC3csIo-Je4
  

• input: NONE

• output:

[
    {
        "id": 80978,
        "username": "neal_carter",
        "email": "[e-mail]",
        "avatar": "https://s3.amazonaws.com/uifaces/faces/twitter/vytautas_a/128.jpg",
        "updated_at": "2017-04-04T07:00:50.812Z"
    },
    {
        "id": 68624,
        "username": "meta_pollich",
        "email": "[e-mail]",
        "avatar": "https://s3.amazonaws.com/uifaces/faces/twitter/bereto/128.jpg",
        "updated_at": "2016-11-02T15:54:55.781Z"
    },
    ...
]

/user/:id

Get specific user info (/user/2 ~ get user info who has id = 2)

• request config:

  • Method: GET
  • Header:

  Content-Type : application/json
  Authorization : Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJqb2huX2RvZSIsInN0YXR1cyI6MSwidXBkYXRlZF9hdCI6IjIwMTctMDgtMzEgMDA6MDA6MDAiLCJpYXQiOjE1MDQyMDA2Mzd9.lVRnRCNB7-5zeq_DKtw0jzn_reTCKK5sYC3csIo-Je4
  

• input: NONE

• output:

{
    "id": "2",
    "username": "davon_corwin",
    "email": "[e-mail]",
    "avatar": "https://s3.amazonaws.com/uifaces/faces/twitter/areandacom/128.jpg",
    "updated_at": "2016-11-24T13:29:42.484Z"
}