node package manager


[WIP] This project is a work in progress and is not recommended for production use

Bottlerockets Logo

NPM Version NPM Downloads Test Coverage

Bottlerockets is an efficient BDD command framework written in Node.js and streams task results with Mocha and Chai. Bottlerockets can be used as a CLI tool or a task queue server to stream human readable statuses of tasks and their JSON results.

Use Cases

  • Run commands with expensive setup/teardown operations
  • Run a persistent task queue server with mocha-filled results
  • CLI interface for your project commands
  • Run commands in a REPL environment
  • Easily scale your bottlerockets


npm install -g bottlerockets

Getting Started

Initialize .rockets.js in the root of your project directory:

bottlerockets init

This will create a .rockets.js file with an example:

  .description('This says hello to the enemy')
    firstName: {
      type: String,
      required: true,
      default: 'Sam'
    lastName: {
      type: String,
      required: true,
      default: 'Hunter'
    intruder: {
      type: Boolean,
      default: false
  .action(function (task, args) {
    describe('first name', function () {
      it('is "John"', function () {
        expect(args.firstName)'John') = args.firstName
    describe('last name', function () {
      it('is not "Doe"', function () {
        expect(args.lastName)'Doe') += ' ' + args.lastName
    describe('is intruder', function () {
      it('should NOT be an intruder', function () {

Then run the test bottlerocket command by running:

bottlerocket welcome --first-name John --last-name Henrick --intruder


$ bottlerocket --help
  Usage: bottlerocket [options] <command> [args]
    welcome                 This says hello to the enemy
    help <cmd>              output help for command
    -h, --help              output usage information
    -V, --version           output the version number
    -r, --require <file>    require js files
    -R, --reporter [value]  mocha reporter (default: "spec")
    -V, --verbose <n>       set logging verbosity


Create a queue with the Bottlerockets launcher:

import Bottlerockets from 'bottlerockets'
import http from 'http'
const rockets = new Bottlerockets({
  // Allow up to 5 tasks per single bottlerocket process 
  maxTasks: 10,
  // Launch up to 10 bottlerocket processes per instance 
  // With maxTasks set to 10, this allows up to 80 tasks 
  // to run simultaneously 
  maxInstances: 8,
  // Shut down bottlerocket processes that have not been 
  // used for 15 minutes 
  sleep: 15,
// Launch 100 rockets at once 
setInterval(function () {
  for (let i = 0; i < 100; i++) {
    rockets.launch('welcome', {
      firstName: 'John',
      lastName: 'Henrick',
      intruder: false,
    }).success(result => {
      console.log('result', result)
    }).catch(err => {
      console.error('error', err)
}, 1000)

Documentation & Community


MIT License. See file for details.


Name GitHub Facebook
Sam Hunter samhunta @samhuntr