liftoff

What is liftoff?

Liftoff is a lightweight CLI framework that helps you build command-line tools. It provides a way to bootstrap your CLI application with support for configuration files, environment variables, and plugins.

What are liftoff's main functionalities?

Command-line Interface Bootstrapping

This feature allows you to bootstrap a CLI application with Liftoff. The code sample demonstrates how to create a new Liftoff instance and launch it, printing the environment information.

const Liftoff = require('liftoff');
const MyApp = new Liftoff({
  name: 'myapp',
  moduleName: 'myapp',
  configName: 'myappfile',
  extensions: {
    '.js': null
  }
});
MyApp.launch({}, (env) => {
  console.log('MyApp is running!');
  console.log('Environment:', env);
});

Configuration File Support

Liftoff supports loading configuration files. The code sample shows how to load a configuration file if it exists and print its contents.

const Liftoff = require('liftoff');
const MyApp = new Liftoff({
  name: 'myapp',
  configName: 'myappfile',
  extensions: {
    '.js': null
  }
});
MyApp.launch({}, (env) => {
  if (env.configPath) {
    const config = require(env.configPath);
    console.log('Loaded config:', config);
  } else {
    console.log('No config file found.');
  }
});

Environment Variable Support

Liftoff can access and utilize environment variables. The code sample demonstrates how to print all environment variables when the CLI application is launched.

const Liftoff = require('liftoff');
const MyApp = new Liftoff({
  name: 'myapp',
  configName: 'myappfile',
  extensions: {
    '.js': null
  }
});
MyApp.launch({}, (env) => {
  console.log('Environment Variables:', process.env);
});

Other packages similar to liftoff

commander

Commander is a popular package for building command-line interfaces. It provides a simple and flexible way to define commands, options, and arguments. Compared to Liftoff, Commander focuses more on command parsing and less on configuration and environment management.

yargs

Yargs is another powerful library for building CLI applications. It offers extensive features for parsing arguments, generating help messages, and handling commands. Yargs provides more built-in utilities for argument parsing compared to Liftoff, which focuses on bootstrapping and configuration.

oclif

Oclif is a framework for building command-line tools, developed by Heroku. It provides a robust structure for creating complex CLI applications with plugins and command management. Oclif is more opinionated and feature-rich compared to Liftoff, which is more lightweight and flexible.

README

liftoff

Launch your command line tool with ease.

What is it?

See this blog post, or read on.

Say you're writing a CLI tool. Let's call it hacker. You want to configure it using a Hackerfile. This is node, so you install hacker locally for each project you use it in. But, in order to get the hacker command in your PATH, you also install it globally.

Now, when you run hacker, you want to configure what it does using the Hackerfile in your current directory, and you want it to execute using the local installation of your tool. Also, it'd be nice if the hacker command was smart enough to traverse up your folders until it finds a Hackerfile—for those times when you're not in the root directory of your project. Heck, you might even want to launch hacker from a folder outside of your project by manually specifying a working directory. Liftoff manages this for you.

So, everything is working great. Now you can find your local hacker and Hackerfile with ease. Unfortunately, it turns out you've authored your Hackerfile in coffee-script, or some other JS variant. In order to support that, you have to load the compiler for it, and then register the extension for it with node. Good news, Liftoff can do that too.

API

constructor(opts)

Create an instance of Liftoff to invoke your application.

An example utilizing all options:

var Hacker = new Liftoff({
  name: 'hacker',
  moduleName: 'hacker',
  configName: 'hackerfile',
  extensions: {
    '.js': null,
    '.json': null,
    '.coffee': 'coffee-script/require'
  },
  processTitle: 'hacker',
  cwdFlag: 'cwd',
  configPathFlag: 'hackerfile',
  preloadFlag: 'require',
  completionFlag: 'completion',
  completions: function (type) {
    console.log('Completions not implemented.');
  }
});

opts.name

Sugar for setting processTitle, moduleName, configName & configPathFlag automatically.

Type: String Default: null

These are equivalent:

new Liftoff({
  processTitle: 'hacker',
  moduleName: 'hacker',
  configName: 'hackerfile',
  configPathFlag: 'hackerfile'
});

new Liftoff({name:'hacker'});

opts.moduleName

Sets which module your application expects to find locally when being run.

Type: String
Default: null

opts.configName

Sets the name of the configuration file Liftoff will attempt to find. Case-insensitive.

Type: String
Default: null

opts.extensions

Set extensions to include when searching for a configuration file. If an external module is needed to load a given extension (e.g. .coffee), the module name should be specified as the value for the key.

Type: Object
Default: {".js":null,".json":null}

Examples

In this example Liftoff will look for myappfile{.js,.json,.coffee}. If a config with the extension .coffee is found, Liftoff will try to require coffee-script/require from the current cwd before calling launch.

var MyApp = new Liftoff({
  name: 'myapp'
  extensions: {
    ".js": null,
    ".json": null,
    ".coffee": "coffee-script/require"
  }
});

In this example, Liftoff will look for .myapp{rc}.

var MyApp = new Liftoff({
  name: 'myapp',
  configName: '.myapp',
  extensions: {
    "rc": null
  }
});

In this example, Liftoff will automatically attempt to load the correct module for any extension supported by node-interpret (as long as it does not require a register method).

var MyApp = new Liftoff({
  name: 'myapp',
  extensions: require('interpret').extensions
});

opts.processTitle

Sets what the process title will be.

Type: String
Default: null

opts.cwdFlag

Sets what flag to use for altering the current working directory. For example, myapp --cwd ../ would invoke your application as though you'd called it from the parent of your current directory.

Type: String
Default: cwd

opts.configPathFlag

Sets what flag to use for defining the path to your configfile. For example, myapp --myappfile /var/www/project/Myappfile.js would explicitly specify the location of your config file. Note: Liftoff will assume the current working directory is the directory containing the config file unless an alternate location is specified using cwdFlag.

Type: String
Default: same as configName

Examples

These are functionally identical:

myapp --myappfile /var/www/project/Myappfile.js
myapp --cwd /var/www/project

These will run myapp from a shared directory as though it were located in another project:

myapp --myappfile /Users/name/Myappfile.js --cwd /var/www/project1
myapp --myappfile /Users/name/Myappfile.js --cwd /var/www/project2

opts.preloadFlag

Sets what flag to use for pre-loading modules. For example, myapp --require coffee-script would require a local version of coffee-script (if available) before attempting to find your configuration file. If your required module registers a new require.extension, it will be included as an option when looking for a file matching configName.

Type: String
Default: "require"

opts.completions(type)

A method to handle bash/zsh/whatever completions.

Type: Function
Default: null

events

require(name, module)

Emitted when a module is pre-loaded.

var Hacker = new Liftoff({name:'hacker'});
Hacker.on('require', function (name, module) {
  console.log('Requiring external module: '+name+'...');
  // automatically register coffee-script extensions
  if (name === 'coffee-script') {
    module.register();
  }
});

requireFail(name, err)

Emitted when a requested module cannot be preloaded.

var Hacker = new Liftoff({name:'hacker'});
Hacker.on('requireFail', function (name, err) {
  console.log('Unable to load:', name, err);
});

launch(fn, argv)

fn(env)

A function to start your application. When invoked, this will be your instance of Liftoff. The env param will contain the following keys:

• argv: cli arguments, as parsed by minimist, or as passed in manually.
• cwd: the current working directory
• preload: an array of modules that liftoff tried to pre-load
• configNameRegex: the regular expression used to find your config file
• configPath: the full path to your configuration file (if found)
• configBase: the base directory of your configuration file (if found)
• modulePath: the full path to the local module your project relies on (if found)
• modulePackage: the contents of the local module's package.json (if found)

argv

Manually specify command line arguments. Useful for invoking the CLI programmatically.

Type: Object
Default: null

Examples

Check out the hacker project to see a working example of this tool.

To try the example, do the following:

1. Install the sample project hacker with npm install -g hacker.
2. Make a Hackerfile.js with some arbitrary javascript it.
3. Install hacker next to it with npm install hacker.
4. Run hacker while in the same parent folder.