Skip to content
🎾Core libraries and example project of how to use @uswitch/koa libraries
Branch: master
Clone or download
Latest commit 676d9a7 Jul 8, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
packages Updated all the package versions Jul 4, 2019
.babelrc 🎾 Add in babel to run test app and fix metric integration Jul 18, 2018
koa-core.js 🀐 Introduction of Koa Zipkin (#22) Jul 3, 2019
merge.js [core] Move into the root of the project Jul 16, 2018

🎾 Koa Core

The core that powers uSwitch Koa services.

Overview | Packages | Library | Example

License type language test style


Koa Core is a lerna monorepo housing all of uSwitch's koa packages.

This repo acts both as a helper library for wiring together the @uswitch/koa- packages as well as a master list of open sources koa libraries that we depend on.

This means we have a single point of truth for which packages we use and the versions we depend on.

npm install @uswitch/koa-core

Making changes

All of our koa libraries can be found in packages. Any changes should be made to them individually. Commits should ideally be namespaced to the package you're changing.

e.g. [access] Making changes to koa access or [core] Making changes to core.

Or, better yet, with emojis

  • 🎾 for core
  • πŸ‘Œ for access
  • πŸ•΅οΈβ€β™€οΈ for tracer
  • 🚦 for signal
  • 🌑️ for prometheus
  • ⏰ for timeout
  • 🀐 for zipkin

Once changes have been committed, we use lerna to manage the bumping and publishing.

# Make sure you're on a branch because of tag push permissions!!

npm run publish:packages

This will publish the individual libraries followed by performing updating dependencies and generating the documentation for core .


@uswitch packages

Package Version Dependencies Description
@uswitch/koa-access npm Dependency Status πŸ‘Œ A Koa middleware for logging JSON access logs consistently, similar to morgan
@uswitch/koa-prometheus npm Dependency Status 🌑️ A configurable Prometheus data collector with Koa middleware
@uswitch/koa-signal npm Dependency Status 🚦 Hackable and configurable output rendering for loggers
@uswitch/koa-timeout npm Dependency Status ⏰ A Koa middleware to handle timeouts correctly
@uswitch/koa-tracer npm Dependency Status πŸ•΅οΈβ€β™€οΈ A koa.js middleware to add namespaced tracing throughout a requests lifecycle
@uswitch/koa-zipkin npm Dependency Status πŸ•΅οΈβ€β™€οΈ A koa.js middleware to add Zipkin tracing to requests

koa packages

Package Version Latest
koa ^2.6.2 npm
koa-bodyparser ^4.2.1 npm
koa-compose ^4.1.0 npm
koa-cookie ^1.0.0 npm
koa-helmet ^4.0.0 npm
koa-requestid ^2.0.1 npm
koa-router ^7.4.0 npm
koa-static ^5.0.0 npm


koa-core can also be used as a boilerplate library to quickly set upo a new Koa server in the same was as the Koa library itself.


import Koa from '@uswitch/koa-core'

const { app, logger } = new Koa()
app.listen(3000, () =>'Applications started on port 3000'))

N.B. koa-core returns an app and a logger

Importing dependencies

All of the koa packages we have are available to import in your project via the following;

/* ES6 Import */
import koaLibrary from '@uswitch/koa-core/koa-library'

/* Require */
const koaLibrary = require('@uswitch/koa-core/koa-library')

See packages for a list of available koa libraries through koa-core.


This project also comes with an Example server and some example routes which shows how we use the @uswitch/koa libraries.

npm install
NODE_ENV=development npm run example
NODE_ENV=production npm run example

This will start the server on port http://localhost:3000 and you can try hitting the following routes to see how it works;

curl http://localhost:3000/hello         // 200 string body
curl http://localhost:3000/hello/world

// Test different status codes
curl http://localhost:3000/status/200
curl http://localhost:3000/status/404
curl http://localhost:3000/status/503

// Test tracing errors as they happen
curl http://localhost:3000/error         // Fatal error
curl http://localhost:3000/multi-errors  // Multiple errors non fatal

// Test tracing behaviour
curl http://localhost:3000/trace/150     // Trace either side of 150ms async
curl http://localhost:3000/scope/name    // Trace message to scope NAME

// See all types of koa-signal message
curl http://localhost:3000/signal/all

// See how zipkin tracing works
curl http://locahost:3000/zipkin
You can’t perform that action at this time.