Catalyst-server is a configuration and composition management tool for Hapi.js applications. It allows for composition and configuration that is environment aware and extensible for a web application. This is managed from a single manifest.json
file. The server also will include sensible defaults and implementations (like hapi-pino for logging and crumb for CSRF).
- Install catalyst-server and hapi into an empty node project with
npm i @vrbo/catalyst-server @hapi/hapi
- Create an
index.js
file for starting your server (example below). - Create a
manifest.json
for composition and configuration (example below). - Start your app
node index.js
const Catalyst = require('@vrbo/catalyst-server');
const Path = require('path');
async function start(options = {}) {
const server = await Catalyst.init({
...options,
userConfigPath: Path.resolve(__dirname, 'manifest.json')
});
await server.start();
server.log(['info'], `server running: ${server.info.uri}`);
return server;
}
start();
{
// server configuration and application context variables.
"server": {
"app": {
}
},
// Hapi plugins
"register": {
}
}
Catalyst-server uses steerage to configure and compose your application. It is environment aware and has some configuration protocols to resolve paths, read environment variables, import other JSON files, and more.
At its core, catalyst-server
loads a manifest.json
file to initialize and start up a Hapi.js server. This file has a section for application configuration and composition via registering plugins.
Below is a basic example of a manifest.json
file:
{
// server configuration and application context variables.
"server": {
"app": {
"urlPrefix": "temp/",
"siteTitle": "temp site"
}
},
// Hapi plugins
"register": {
"Inert": {
"register": "require:inert"
},
"Vision": {
"register": "require:vision",
"options": {
"engines": {
"html": "require:handlebars"
},
"path": "path:./templates"
}
}
}
}
You can access all the configuration values in your code from the server.app.config
object. So the code to retrieve the example values looks like this:
const urlPrefix = server.app.config.get('urlPrefix');
const siteTitle = server.app.config.get('siteTitle');
The register
block registers the plugins referenced. In this example, it is using shortstop to resolve node modules using require:[module]
and resolve paths using path:[file_path]
.
Catalyst-server ships with the following shortstop
resolvers by default:
- file - read a file.
- path - resolve a path.
- base64 - resolve a base64 string.
- env - access an environment variable.
- require - require a javascript or json file.
- exec - execute a function in a file.
- glob - match files using the patterns shell uses.
- import - imports another JSON file, supports comments.
- eval - safely execute a string as javascript code.
Steerage
uses confidence to give you the ability to build environmentally aware servers. See the example manifest.json
file below.
{
// server configuration and application context variables.
"server": {
"app": {
"urlPrefix": {
"$filter": "env.NODE_ENV",
"production":"/application",
"$default":"/temp"
}
}
},
// Hapi plugins
"register": {
"crumb": {
"register": "require:crumb",
"options": {
"cookieOptions": {
"isSecure": {
"$filter": "env.NODE_ENV",
"development": false,
"$default": true
}
},
"restful": true
}
}
}
}
In this example, the $filter
and $default
fields allow for filtering based on a resolver like env.NODE_ENV
.
The $filter
field evaluates the environment variable NODE_ENV
. Then, it will look to the following fields for a match in the keys for that value. Otherwise, the $default
value is used. So the configuration values and options for plugins will change based on the environment variable NODE_ENV
.
This is what the above manifest configuration will return in code for different environments:
// ENVIRONMENT VARIABLE NODE_ENV='development'
const urlPrefix = server.app.config.get('urlPrefix');
// returns '/temp'
// crumb will NOT use secure cookies.
// ENVIRONMENT VARIABLE NODE_ENV='production'
const urlPrefix = server.app.config.get('urlPrefix');
// returns '/application'
// crumb WILL use secure cookies.
Using a filter, you can easily enable/disable a plugin for a given environment. See the code below for an example, where we disable hapi-pino
in development mode, and enable it in all other environments:
{
"register": {
"hapi-pino": {
"enabled": {
"$filter": "env.NODE_ENV",
"development": false,
"$default": true
}
}
}
}
Here are some examples of the shortstop
resolvers which make handling complex configuration and composition rather straight forward.
"key": "file:./pgp_pub.key"
- loads the file
pgp_pub.key
and will set the valuekey
to the contents of that file.
"path": "path:./templates"
- will resolve the path of
./templates
and will set the valuepath
to the fully resolved path.
"bytes": "base64:SGVsbG8="
- will decode the base64 string
SGVsbG8=
and will set thebytes
value to a buffer from the base64 string.
"dbHost": "env:PG_HOST"
- will evaluate the environment variable
PG_HOST
and will set thedbHost
value to the environment variable value.
"register": "require:inert"
- will load the node module
inert
and will set theregister
to what that module exports. This works for js files in you application.
"status": "exec:./callStatus#get"
- will load the file
callStatus.js
and will run the exported functionget
and whatever value is return will be set for thestatus
value.
"files": "glob:./assets/**/*.js"
- will use glob to evaluate
./assets/**/*.js
and sets the value offiles
to an array of files that match the glob string.
"data": "import:./data/salt.json"
- will load a json file
./data/salt.json
, evaluate it (ignoring comments) and setdata
to that value.
"start": "eval:new Date().toISOString()"
- will use vm to evaluate the string and set the
start
to the current date time as an ISO string.
{
"server": {
"app":{
"first": "abc",
"second": "xyz",
"child": {
"value":"eval:${server.app.first}_${server.app.second}"
}
}
}
}
eval
can also be used to reference other values in themanifest
. In the above example thechild/value
inserver/app
will be set to'abc_xyz'
.
See the examples folder for example code.