Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/npkgz/koa-magic
Koajs supercharged. routing. ready-to-use server
https://github.com/npkgz/koa-magic
koa2 koajs middleware router routing web-application
Last synced: 30 days ago
JSON representation
Koajs supercharged. routing. ready-to-use server
- Host: GitHub
- URL: https://github.com/npkgz/koa-magic
- Owner: npkgz
- License: mit
- Created: 2018-03-05T20:36:39.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-12-07T01:07:04.000Z (almost 2 years ago)
- Last Synced: 2024-10-14T15:01:33.078Z (30 days ago)
- Topics: koa2, koajs, middleware, router, routing, web-application
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/koa-magic
- Size: 181 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
koa-magic
=========================================
koa supercharged. middleware library. ready-to-go web-application-server based on [koajs v2](https://github.com/koajs/koa)
## 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](https://github.com/AndiDittrich/Node.cluster-magic)
* Sendfile implementation
* Static fileserver implementation
## Install ##
```bash
$ npm install koa-magic --save
$ yarn add koa-magic
```
## Modules ##
koa-magic provides the following modules
```js
const {Koa, Router, ApplicationServer, ErrorLogger, Dispatcher} = require('koa-magic');
```
* [Koa](docs/koa.md) - Extended Koa class including routing methods
* [Router](docs/router.md) - Stackable - express like - routing middleware
* [ApplicationServer](docs/application-server.md) - Ready-to-use Koa webserver including basic middleware (compress, sessions)
* [ErrorLogger](docs/error-logger.md) - error-logging middleware - exceptions are logged by [logging-facility](https://www.npmjs.com/package/logging-facility)
* [Dispatcher](docs/dispatcher.md) - routing middleware dispatcher (used by Router)
## Koa Extend ##
Basic [Koa Class](https://github.com/koajs/koa/blob/master/lib/application.js) extended by routing methods.
### Examples ###
**Example 1 - path routing**
```js
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](https://github.com/pillarjs/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**
```js
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**
```js
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**
```js
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)](http://opensource.org/licenses/MIT) - your're welcome to contribute