koa-magic

koa supercharged. routing. middleware library. ready-to-go web-application-server

Usage no npm install needed!

<script type="module">
  import koaMagic from 'https://cdn.skypack.dev/koa-magic';
</script>

README

koa-magic

koa supercharged. middleware library. ready-to-go web-application-server based on koajs v2

Features

  • Stackable routing middleware
  • Path-Match Router
  • VHost Router (domain/hostname based)
  • Easy to use application server including basic koa modules
  • Components can be used standalone
  • Cluster support/Hot-Reload via cluster-magic
  • Sendfile implementation
  • Static fileserver implementation

Install

$ npm install koa-magic --save
$ yarn add koa-magic

Modules

koa-magic provides the following modules

const {Koa, Router, ApplicationServer, ErrorLogger, Dispatcher} = require('koa-magic');
  • Koa - Extended Koa class including routing methods
  • Router - Stackable - express like - routing middleware
  • ApplicationServer - Ready-to-use Koa webserver including basic middleware (compress, sessions)
  • ErrorLogger - error-logging middleware - exceptions are logged by logging-facility
  • Dispatcher - routing middleware dispatcher (used by Router)

Koa Extend

Basic Koa Class extended by routing methods.

Examples

Example 1 - path routing

const Router = require('koa-magic').Router;
const Koa = require('koa-magic').Koa;

// initialize koa + router
const webapp = new Koa();
const myrouter = new Router();

// attach handler to root path
koa.get('/helloworld.html', ctx => {
    ctx.body = 'Helloworld';
});

// attach router middleware - use attach() of extended Koa!
koa.attach('/hello', myrouter);

// start server
koa.listen(...);

Router

The mount-path is processed by path-to-regexp to enable parametric path expressions. The parameters are exposed by the ctx.params object.

Note: use .attach() instead of .use() to add middleware to the stack. It handles flat middleware functions like (ctx, next) => {} as well as instances of Router!

Methods

The following methods are provided by each routing instance (or extended Koa class)

HTTP

  • get(path:string|RegExp, middleware:Promise) handle http-get
  • post(path:string|RegExp, middleware:Promise) handle http-post
  • put(path:string|RegExp, middleware:Promise) handle http-put
  • head(path:string|RegExp, middleware:Promise) handle http-head
  • delete(path:string|RegExp, middleware:Promise) handle http-delete
  • options(path:string|RegExp, middleware:Promise) handle http-options
  • all(path:string|RegExp, middleware:Promise) handle all kind of http-methods

VHOST

  • vhost(hostname:string|RegExp, middleware:Promise|Router) virtual host routing

ROUTING

  • attach(path:string|RegExp, middleware:Promise|Router) add a new router to the current stack (like use)

Examples

Example 1 - path routing

const Router = require('koa-magic').Router;
const Koa = require('koa-magic').Koa;

// initialize koa + router
const webapp = new Koa();
const myrouter = new Router();

myrouter.get('/world.html', ctx => {
    ctx.body = "ook";
});
myrouter.post('/:action/:view?', ctx => {
    ctx.body = "action:" + ctx.params.action + ' - ' + ctx.params.view;
});

// attach handler to root path
koa.get('/helloworld.html', ctx => {
    ctx.body = 'Helloworld';
});

// attach router middleware - use attach() of extended Koa!
koa.attach('/hello', myrouter);

// start server
koa.listen(...);

Example 2 - path routing with request forwarding

const Router = require('koa-magic').Router;
const Koa = require('koa-magic').Koa;

// initialize koa + router
const webapp = new Koa();
const myrouter = new Router();

myrouter.get('(.*)', (ctx, next) => {
    dosomething();
    return next();
});
myrouter.post('/:action/:view?', ctx => {
    ctx.body = "action:" + ctx.params.action + ' - ' + ctx.params.view;
});

// attach router middleware - use attach() of extended Koa!
koa.attach('/mymodule', myrouter);

// start server
koa.listen(...);

Example 3 - vhost routing

const Router = require('koa-magic').Router;
const Koa = require('koa-magic').Koa;

// initialize koa + router
const webapp = new Koa();
const myrouter = new Router();

myrouter.get('/world.html', ctx => {
    ctx.body = "ook";
});

// attach router middleware to domain
koa.vhost('example.org', myrouter);

// start server
koa.listen(...);

License

koa-magic is OpenSource and licensed under the Terms of The MIT License (X11) - your're welcome to contribute