polyapp v0.1.0

PolyApp

Runs Express applications as modules

PolyApp is a simple package which aims to solve two needs:

• Create Express applications without the hurdle of reimplementing the server logic
• Easy deploying of containers which have one or more Express modules

Table of Contents

• Installation
• How it works
• Usage
  • Module example
• Documentation
• Contributing
  • Bug reports, feature requests and discussion
  • Developing
  • Features wishlist
• License
• Frequently Asked Questions

Installation

PolyApp is available on npm. To be able to create a container with PolyApp and some modules you need to install the PolyApp dependency first:

npm install --save polyapp

How it works

There are two elements:

• PolyApp (this package) which runs a instance of Express framework.
• PolyApp modules which simply exposes a Express router.

You can create a container to deploy as many (or less) modules as you want simply following the next steps:

1. Install PolyApp (using npm) and your modules (with npm, git submodules, placing them on a folder or whatever you prefer)
2. Require PolyApp and your modules
3. Create a instance of PolyApp
4. Include your modules in PolyApp
5. Start the PolyApp server

Done! You can see steps 2 to 5 in next section.

Usage

Here you have a container example. You simply initialize PolyApp and include as many modules as you want. There is a basic module example following this piece of code.

var PolyApp = require('../polyapp');
var poly = new PolyApp();
poly.port = 8080;

var testModule = require('./test_module');

poly.include(testModule);

poly.start();

Module example

This example is very stupid but it works for illustrating the API. Modules become more interesting when your router exposes full services with multiple endpoints.

var express = require('express');
var OK_STATUS_CODE = 200;

module.exports = function Module(server, options) {
  this.router = express.Router();

  this.router.get('/test', function(req, res, next) {

    res.status(OK_STATUS_CODE).send('It works!');
  });
};

Documentation

Documentation is available here.

Contributing

Bug reports, feature requests and discussion

Feel free to use the GitHub issue tracker to report any bugs or file feature requests. In case you found a bug and have no GitHub account, feel free to email me: fcanela.dev at gmail dot com.

Developing

Pull requests are welcome. I also love technical discussions, so feel free to open a issue on the tracker.

To begin developing clone the GitHub repository and install dependencies with npm install.

The module has some npm scripts which could be useful for developing purpose:

• npm start watches for changes and runs tests
• npm run health lints the library and runs tests
• npm run docs generates the markdown documentation from JsDocs

Features wishlist

• CORS fast and easy management
• Cluster
• API to include middleware

License

Copyright (c) 2016 Francisco Canela. Licensed under the MIT license.

Frequently Asked Questions

Is the code production ready?

This project uses Semver for versioning.

Until the software reaches 1.0.0 I would discourage the use for non-recreative projects.

Why Express instead of Koa?

Koa will break the routes callback API as soon as async/await support is introduced in Node (source). I may migrate PolyApp to Koa when that happens. The later have a lot of features that fits with the project concept.

What about HTTPS?

A reverse proxy (for example, nginx) in front of PolyApp should work. It also makes updating the certificates and configuring SSL a lot easier.

If a reverse proxy does not solve your problem, please, open a issue explaining your case so we can discuss about it.

Isn't this a framework? Why anoooother one?

This project is so simple that I hesitate to call it framework, but as it forces you to certain architecture yes, it could be considered a framework.

Worse, this can be considered a framework on top of another framework. Please, ask your deity for my forgiveness: I created another monster.

My excuse: It solves a problem that I have.