🎾 An example project showing the user of all core `@uswitch/koa` libraries

Usage no npm install needed!

<script type="module">
  import uswitchKoaCore from 'https://cdn.skypack.dev/@uswitch/koa-core';


🎾 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 .

This publishes to both the NPM and Github Packages Registries

Node Version

koa-core was built using Node v10 so you should run the following when developing it.

nvm use


@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-cookie | npm | Dependency Status | 🍪 Koa cookie parser middleware | | @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-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, () => logger.info('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