villeristi / koa-api-boilerplate

A Boilerplate for modern API's with Koa

Koa API Boilerplate

Easily configurable & scalable API-only boilerplate for blazingly fast Koajs-framework with JSON API specification & ES6-syntax included out-of-the-box!

Built with:

• Koa
• Koa Better Router
• Koa Better Body
• Cors
• Helmet
• JOI schema-validator
• JSONAPI Serializer
• Babel
• Morgan
• Debug
• ESLint
• Yarn
• ...and many more

Getting started

1. Be sure you have Yarn installed globally.
2. Clone the repo & run yarn from the project root
3. Copy .env.example to .env

Routing

Routing is a consept which should be dead simple. In this boilerplate routing is configured through routes.js file by adding a new key-value pair to default exported object, where key is a combination of HTTP-verb and a route-path, e.g. 'GET /foobar'.

values only required property is a handler-function which takes a ctx & next (see context-documentation) properties. You can also define as many middleware-functions inside values middleware-array. Middleware-functions are executed in the same order they are specified in the array.

For handler-method, both regular and async-functions are supported.

Out-of-the-box provided routes:

GET /           => App name etc.
GET /users      => List (dummy)users
GET /users/:id  => Show single user
POST /users     => "create" a dummy-user

Please see routes.js & src/modules/user folder for in-depth examples of how to configure things.

Available commands

yarn start

Runs Babel watch-command & starts server on http://127.0.0.1 on PORT specified in .env -file (defaults to 8080, http://127.0.0.1:8080).

Note! To start debugging (on DEV), start the app on Linux / OSX with DEBUG=koa-api-boilerplate yarn start and on Windows with set DEBUG=koa-api-boilerplate yarn start

yarn lint

Lints JS-files inside /src directory

yarn build

Transforms ES6-syntax and builds (+minifies) the project to /build directory.

Todo:

• Testing
• Route-grouping
• ...?