readme.md

koa-framework

Dead simple framework on top of koa

Koa framework is a basic bootstrap library for creating a Koa server. It provides a router constructor with basic middleware such as a request parser and validator.

Usage

Step 1 - Add the base koa server as a dependency

npm install koa-framework --save

Step 2 - Create an app

A koa instance is returned so see koa documentation for more details.

let koa = require('koa-framework');

// koa server instance
let app = koa();

Step 2 - Add some app logic

Request body is automatically parsed using koa-body-parser. Both json and form encodings are supported.

Create router instance

See koa-router documentation for detailed documentation.

let router = app.router();

router.get('/test', function *() {
	this.body = 'Wow! just like Express';
});

// mount router
app.mount(router);

Data validation

One of the key aspects of a web application is data validation. koa-framework supports request data validation using jsonschema. If data does not pass validation, the server returns a 400 Bad Request error. In non production environments, the response body is populated with the validation errors.

let schema = {
	params: {
		properties: {
			object: { type: 'string', required: true }
		}
	},
	query: {
		properties: {
			something: { type: 'string', required: false } }
		}
	},
	body: {
		properties: {
			password: { type: 'string', required: true, minLength: 10 }
		}
	}
};
router.post('/secret/:object', app.schema(schema), function *() {
	let body = this.request.body;

	if (body.password === 'the best password ever') {
		this.body = 'You got it boss';
	} else {
		this.throw(403, 'Pffttt...');
	}
});

The server returns the following response body on schema validation error. The validationErrors property is the errors property returned by jsonschema on validation.

{
	"error": "Invalid request parameters",
	"validationErrors": [{
		"property": "request.body",
		"message": "Property password is required",
		"schema": { ... },
		"instance": ...
	}]
}

Namespaced routes and middleware

// private routes
let paymentsRouter = app.router({
	prefix: '/payments'
});

// middleware for /payments/*
paymentsRouter.use(ensureAuthenticated);

// POST /payments/transfer
paymentsRouter.post('/transfer', handleTransfer);


// public routes
let sharedRouter = app.router({
	prefix: '/shared'
});

// GET /shared/lolcat
sharedRouter.get('/lolcat', getLolcat);

app.mount(paymentsRouter, sharedRouter);

// alternatively
app.mount(paymentsRouter);
app.mount(sharedRouter);

Step 3 - Kick off the server

app.listen();

Bundled middleware

koa-framework comes bundled with koa-body-parser, koa-error and koa-x-request-id

Configuration

Middlewares are completely configurable with options being passed to the downstream middleware as is. Optionally, individual middlewares can also be turned off completely. An example is shown below:

var app = koa({
	middleware: {
		error: { enabled: false },
		parse: { jsonLimit: '512kb' },
		requestId: { key: 'x-request-id'. inject: false }
	}
});

Changelog