kapp v0.3.0

Kondoot Application Template (Kapp)

This repository is designed to make the process of creating node applications that fit into the stack used at Kondoot super simple and repeatable.

Creating a Kapp

Creating a Kapp is very simple, and basic initialization goes as follows:

var app = require('kapp')('appname');

Options can be specified that influence how a Kapp behaves, and these are covered in more detail later. Once you have completed your application specific initializations you then call app.start() to get the application to load handlers, configuration information, start the default application server (restify is used by default), etc.

When the application is ready and serving requests it will fire the ready event, and if the app.start() call is supplied a callback that will be called shortly after the ready event is triggered.

Baseline package.json for a Kapp

The following represents a baseline package.json file that should be used to create new a new Kondoot node application:

{
  "name": "appname",
  "description": "Application Description",
  "author": "Kondoot <development@kondoot.com>",
  "tags": [
    "build"
  ],
  "version": "0.0.0",
  "engines": {
    "node": ">= 0.6.x < 0.9.0"
  },
  "dependencies": {
    "kapp": "../kapp",
    "restify": "1.4.x"
  },
  "devDependencies": {
  },
  "repository": {
    "type": "git",
    "url": "git://github.com/kondoot/appname.git"
  },
  "bugs": {
    "url": "http://github.com/kondoot/appname/issues"
  },
  "scripts": {
    "test": "./node_modules/.bin/mocha --reporter spec --timeout 30000"
  },
  "contributors": []
}

Handler Loading

One of the helpful things that Kapp does for you is load route handlers from a handlers directory from within your application structure. For instance consider the following:

- handlers
|- echo.js
|- hello.js
- server.js
- package.json

In the case above, during initialization Kapp will have autodiscovered the echo and hello handlers for you and wired them into the handlers object (app.handlers.echo and app.handlers.hello respectively). It's important to note however that the handlers are not connected to the server instance in any way as defining route handlers and directing them to the handlers is the responsibility of the application.

In terms of the actual handler functions, you are essentially implementing handlers that are identical to the application server you are using in your Kapp application (restify by default), but with a leading app argument that is injected by Kapp:

// an example echo handler
module.exports = function(app, req, res, next) {
    res.end(req.body);
};

This app argument will allow you to access your application object within your handlers without having to try and manage messy external references to the object.

Defining Application Routes

To specify your application routes, the best time to do this is in response to the started event that is emitted by a Kapp:

app.once('started', function(server) {
    server.get('/hello', app.handlers.hello);
});

Advanced: Using a server framework other than RESTify

To be completed.