@retailmenot/roux-server v1.0.5

@retailmenot/roux-server

Express application that serves a pantry of ingredients for the Roux ecosystem.

Installation

npm install @retailmenot/roux-server

Usage

Initialization

This module exports a function that returns an initialized Express 4 application, suitable for stand-alone use or mounting on a route as a sub-application. The function expects a configuration object with two required properties: baseDir and namespace, naming the location of the pantry of ingredients and its namespace, respectively.

Stand-alone

The returned application instance can be used like any Express application, including adding additional middleware and routes. The simplest usage is to just serve the pantry of ingredients:

var pantryDir = './path/to/pantry';
var pantryName = 'pantry-name';
var app = require('@retailmenot/roux-server')({
  baseDir: pantryDir,
  namespace: pantryName,
});

var server = app.listen(8080, function () {
	var host = server.address().address;
	var port = server.address().port;

	console.log(
    'Serving %s ingredients from %s at http://%s:%s',
    pantryName,
    pantryDir,
    host,
    port
  );
});

As a sub-application

In more complicated applications, it may be better to use the returned application as a sub-application:

var express = require('express');
var app = express();

var pantryDir = './path/to/pantry';
var pantryName = 'pantry-name';
var ingredientApp = require('@retailmenot/roux-server')({
  baseDir: pantryDir,
  namespace: pantryName,
});

app.use('/ingredients', ingredientApp);

var server = app.listen(8080, function () {
	var host = server.address().address;
	var port = server.address().port;

	console.log(
    'Serving %s ingredients from %s at http://%s:%s/ingredients',
    pantryName,
    pantryDir,
    host,
    port
  );
});

As a global CLI

If you simply wish to serve a local pantry without any advanced configuration, the CLI may well suit your needs:

$ npm install -g @retailmenot/roux-server

$ pushd path/to/pantry

$ roux-server --namespace 'your-pantry-namespace'

Providing helpers

In the CLI, you can provide helpers arguments which will register helpers on the Handlebars instance.

The helpers argument accepts a module path which behaves similarly to a require() from the current working directory.

For example:

• ./foo will resolve to ./foo
• ../foo will resolve to ../foo
• /foo will resolve to /foo
• foo will attempt to read ./node_modules/foo, then fall back to ./foo

A path should resolve to a module which exports an object mapping helper names to functions.

Multiple paths can be specified by providing multiple helpers arguments. These will be applied left-to-right, with collisions in helper names ceding to the right-most declared helper.

For example, given:

// a.js

module.exports = {
  a: function () {
    return 'a';
  }
};

// alwaysSayDogs.js

module.exports = {
  a: function () {
    return 'dogs';
  },
  b: function () {
    return 'dogs';
  }
}

The following commands would register helpers as illustrated:

roux-server --helpers a --helpers alwaysSayDogs
a -> dogs
b -> dogs

roux-server --helpers alwaysSayDogs --helpers a
a -> a
b -> dogs

API

Module

The module exports a function that returns an initialized Express application.

• config - Configuration object for the application instance
  • baseDir - path to the pantry of ingredients to serve
  • namespace - the namespace used by ingredients in the pantry
  • [defaultModel] - the model to use as the Handlebars context if an ingredient does not provide a model entrypoint. Defaults to {}.
  • [defaultPreviewTemplatePath] - path to the default preview template to use if an ingredient does not provide a preview entrypoint. Defaults to default-preview.
• [callback] - an optional Node-style callback that is called when the server is fully initialized and ready to respond to requests

Application

The application instances returned are Express 4 Application instances.

Development / Contributing

$ git clone ssh://git@github.com:RetailMeNotSandbox/roux-server.git roux-server && cd $_

## install dependencies
$ npm install

## ensure grunt-cli is installed globally
$ npm install -g grunt-cli

## run linter
$ grunt eslint