https://github.com/uswitch/koa-core
🎾 Core libraries and example project of how to use @uswitch/koa libraries
https://github.com/uswitch/koa-core
Last synced: 9 months ago
JSON representation
🎾 Core libraries and example project of how to use @uswitch/koa libraries
- Host: GitHub
- URL: https://github.com/uswitch/koa-core
- Owner: uswitch
- Created: 2018-06-18T10:27:20.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2025-10-02T16:05:19.000Z (9 months ago)
- Last Synced: 2025-10-09T19:32:25.229Z (9 months ago)
- Language: JavaScript
- Homepage:
- Size: 9.43 MB
- Stars: 16
- Watchers: 37
- Forks: 5
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
🎾 Koa Core
The core that powers uSwitch Koa services.
Overview
|
Packages
|
Library
|
Example
[]()
[](https://facebook.github.io/jest/)
[](https://standardjs.com)
## Overview
**Koa Core** is a [`lerna`](https://github.com/lerna/lerna) monorepo
housing all of **uSwitch**'s `koa` packages.
This repo acts both as a **helper** library for wiring together the
[`@uswitch/koa-`](https://github.com/uswitch/koa-core/tree/master/packages) 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`](https://github.com/uswitch/koa-core/tree/master/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.
```sh
# 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
N.B. Conflicts when publishing
> `ERR! lifecycle "publish" errored in "@uswitch/koa-access", exiting 1`
> You may see _conflicts_ when publishing all packages caused by `@uswitch/koa-access`.
> This will error before `@uswitch/koa-core` is published itself
> You can run `npm publish` from within the root of each package to publish them individually.
### Node Version
You can see which version of node `koa-core` supports by looking in [.nvmrc](./.nvmrc).
## Packages
#### `@uswitch` packages
| Package | Version | Dependencies | Description |
|--|--|--|--|
| [`@uswitch/koa-access`](https://www.npmjs.com/package/@uswitch/koa-access) | [](https://www.npmjs.com/package/@uswitch/koa-access) | [](https://david-dm.org/@uswitch/koa-access?path=packages/@uswitch/koa-access) | 👌 A Koa middleware for logging JSON access logs consistently, similar to morgan |
| [`@uswitch/koa-cookie`](https://www.npmjs.com/package/@uswitch/koa-cookie) | [](https://www.npmjs.com/package/@uswitch/koa-cookie) | [](https://david-dm.org/@uswitch/koa-cookie?path=packages/@uswitch/koa-cookie) | 🍪 Koa cookie parser middleware |
| [`@uswitch/koa-prometheus`](https://www.npmjs.com/package/@uswitch/koa-prometheus) | [](https://www.npmjs.com/package/@uswitch/koa-prometheus) | [](https://david-dm.org/@uswitch/koa-prometheus?path=packages/@uswitch/koa-prometheus) | 🌡️ A configurable Prometheus data collector with Koa middleware |
| [`@uswitch/koa-signal`](https://www.npmjs.com/package/@uswitch/koa-signal) | [](https://www.npmjs.com/package/@uswitch/koa-signal) | [](https://david-dm.org/@uswitch/koa-signal?path=packages/@uswitch/koa-signal) | 🚦 Hackable and configurable output rendering for loggers |
| [`@uswitch/koa-timeout`](https://www.npmjs.com/package/@uswitch/koa-timeout) | [](https://www.npmjs.com/package/@uswitch/koa-timeout) | [](https://david-dm.org/@uswitch/koa-timeout?path=packages/@uswitch/koa-timeout) | ⏰ A Koa middleware to handle timeouts correctly |
| [`@uswitch/koa-tracer`](https://www.npmjs.com/package/@uswitch/koa-tracer) | [](https://www.npmjs.com/package/@uswitch/koa-tracer) | [](https://david-dm.org/@uswitch/koa-tracer?path=packages/@uswitch/koa-tracer) | 🕵️♀️ A koa.js middleware to add namespaced tracing throughout a requests lifecycle |
| [`@uswitch/koa-zipkin`](https://www.npmjs.com/package/@uswitch/koa-zipkin) | [](https://www.npmjs.com/package/@uswitch/koa-zipkin) | [](https://david-dm.org/@uswitch/koa-zipkin?path=packages/@uswitch/koa-zipkin) | 🕵️♀️ A koa.js middleware to add Zipkin tracing to requests |
#### `koa` packages
| Package | Version | Latest |
|--|--|--|
| [`koa`](https://www.npmjs.com/package/koa) | `^2.15.4` | [](https://www.npmjs.com/package/koa) |
| [`koa-bodyparser`](https://www.npmjs.com/package/koa-bodyparser) | `^4.2.1` | [](https://www.npmjs.com/package/koa-bodyparser) |
| [`koa-compose`](https://www.npmjs.com/package/koa-compose) | `^4.1.0` | [](https://www.npmjs.com/package/koa-compose) |
| [`koa-helmet`](https://www.npmjs.com/package/koa-helmet) | `^4.0.0` | [](https://www.npmjs.com/package/koa-helmet) |
| [`koa-requestid`](https://www.npmjs.com/package/koa-requestid) | `^2.0.1` | [](https://www.npmjs.com/package/koa-requestid) |
| [`koa-router`](https://www.npmjs.com/package/koa-router) | `^7.4.0` | [](https://www.npmjs.com/package/koa-router) |
| [`koa-static`](https://www.npmjs.com/package/koa-static) | `^5.0.0` | [](https://www.npmjs.com/package/koa-static) |
## Library
`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](https://github.com/koajs/koa) itself.
### Usage
```js
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**](#packages) we have are available to import in your
project via the following;
```js
/* ES6 Import */
import koaLibrary from '@uswitch/koa-core/koa-library'
/* Require */
const koaLibrary = require('@uswitch/koa-core/koa-library')
```
See [**packages**](#packages) for a list of available `koa` libraries
through `koa-core`.
## Example
This project also comes with an [**Example
server**](https://github.com/uswitch/koa-core/blob/master/__example__/server.js)
and some example
[**routes**](https://github.com/uswitch/koa-core/blob/master/__example__/server-routes.js)
which shows how we use the `@uswitch/koa` libraries.
```sh
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;
```sh
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
```
To test zipkin
```sh
docker run --rm -p 9411:9411 --name zipkin openzipkin/zipkin
```
You should then be able to see the UI here: http://localhost:9411/zipkin/
Then run the server with the `ZIPKIN_HOST` env variable set and you should be able to curl `/zipkin` to see the tracing.
```sh
ZIPKIN_HOST=http://127.0.0.1:9411/api/v2/spans NODE_ENV=development npm run example
// See how zipkin tracing works
curl http://locahost:3000/zipkin
```