microboot

microboot

Boot up your app in wee little modules with the help of glob.

microboot([
  'boot/databases',
  'boot/logging',
  'api/**',
  'listeners'
], function () {
  console.log('App booted!')
})

Contents

• Introduction
• How it works
• Examples
• API reference
• Debugging

Introduction

microboot is a small helper designed to facilitate booting up complex applications that we all have. Database connections need to be made, logging services initialised and it all ends up happening nastily at the top of the file.

Using microboot helps you organise your start-up by initialising your app step-by-step, reading file structures to grab everything you need.

Uses

I use this tool for booting APIs and microservices within our architecture. microboot lends itself really well to this as each endpoint can be instantiated in a single, isolated file and the only configuration needed to hook these together is microboot.

// index.js
require('microboot')(['endpoints'])

// connections/api.js
const express = require('express')
const api = express()
api.listen(3000)
module.exports = api

// endpoints/get/list.js
const api = require('../../connections/api')

module.exports = () => {
  api.get('/list', handler)
}

function handler (req, res) => {...}

In that example:

• index.js (our entry point) triggers microboot to grab everything in the endpoints folder
• endpoints/get/list.js is found and required
• connections/api.js is required which set ups a single Express API
• endpoints/get/list.js adds a GET endpoint
• :tada:

While this is a very simple example and it could arguably be clearer having everything in a single file, the key here is extensibility. Having each endpoint separated into an individual file means adding or removing endpoints is as simple as adding or removing a file. No extra work needed.

How it works

In your main file, use microboot as it's used above, specifying the paths of files you want to run in the order you want them to run in. Each element in the given array is a different "phase" and files within each are sorted alphabetically to run. Here's our example:

var microboot = require('microboot')

microboot([
  'boot/databases',
  'utils/logging.js',
  'lib/endpoints/**'
], function (arg) {
  console.log('Ready!')
})

In the files you choose to run, ensure they export a function that will be triggered when microboot iterates through. You can optionally map two parameters: one that's passed through all functions, allowing you to build the object as it goes through and system and the done argument which makes the step asynchronous. Here are two examples:

// boot/databases/mongodb.js
module.exports = function mongodb (arg, done) {
  connectToMongoDb(function (connection) {
    arg.mongo = connection

    return done()
  })
}

// lib/endpoints/post/login.js
module.exports = function post_login (arg) {
  arg.api.newAppEndpoint('post', '/login')
}

You're set! microboot will now first run all JS files found in the boot/databases folder (recursively) including our mongodb.js, then specifically utils/logging.js, then all JS files found in the lib/endpoints folder (recursively) including our login.js.

If you want to know more about the syntax used for specifying recursiveness and the like, take a look at glob; it's what's behind microboot's loader.

Failing to initialise

If something screws up, you should want to stop your app starting. If that's the case, you can throw an error during a step to stop things in their tracks.

For a synchronous step, just go ahead and throw:

module.exports = function my_broken_api () {
  throw new Error('Oh no! It\'s all gone wrong!')
}

For an asynchronous step, return your error as the first argument of the callback:

module.exports = function my_broken_api (arg, done) {
  startUpApi(function (err) {
    if (err) {
      return done(err)
    }

    return done()
  })
}

Examples

Yay examples! These all assume the following directory tree, the root representing your project's current working directory.

.
├── bin
│   └── example
├── boot
│   ├── 01_logging
│   │   ├── bunyan.js
│   │   └── postal.js
│   ├── 02_amqp.js
│   └── 03_database.js
├── index.js
├── lib
│   ├── types
│   │   ├── adding.js
│   │   ├── dividing.js
│   │   ├── multiplying.js
│   │   └── subtracting.js
│   └── utils
│       ├── 404.png
│       ├── deleteFile.js
│       ├── doNothing.js
│       ├── getFile.js
│       └── hugFile.js
├── package.json
└── test
    └── test.js

7 directories, 17 files

Running everything in boot

Runs in order: bunyan.js, postal.js, amqp.js, database.js

microboot(['boot'])

Running everything in boot, then all utils

Runs in order: bunyan.js, postal.js, amqp.js, database.js, deleteFile.js, doNothing.js, getFile.js, hugFile.js

microboot(['boot', 'lib/utils'])

Running 01_logging after 02_amqp.js and 03_database.js

Runs in order: 02_amqp.js, 03_database.js, bunyan.js, postal.js

microboot(['boot/*', 'boot/logging'])

API reference

microboot(phases, [arg], [callback])

• phases - An array of file paths (from the CWD) from which to load Microboot's list of functions to run.
• arg - Optional, defaults to {} A single argument that is passed through every function run, allowing you to mutate it to build up the service as it boots. If arg is a function and no callback has been provided, arg will instead be used as the callback.
• callback(arg) - Optional The function to run once all phases have been successfully run. Is passed the final, mutated arg.

phase([arg], [callback])

• arg - Optional The arg that's being passed through each phase run. Can be specified in the microboot call or defaults to {}.
• callback(err) - Optional If this is mapped to your phase function the phase will be treated as asynchronous and will require that this callback is run before moving to the next one. If there's an error, pass it back as the first parameter.

Debugging

If microboot doesn't seem to be behaving properly, set the DEBUG=microboot* environment variable, run your app and create a new issue with those logs.