Launch your command line tool with ease.
See this blog post, check out this proof of concept, 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, and a whole lot more, too.
Create an instance of Liftoff to invoke your application.
An example utilizing all options:
const Hacker = new Liftoff({
name: 'hacker',
processTitle: 'hacker',
moduleName: 'hacker',
configName: 'hackerfile',
extensions: {
'.js': null,
'.json': null,
'.coffee': 'coffee-script/register'
},
v8flags: ['--harmony'] // or v8flags: require('v8flags');
});
Sugar for setting processTitle
, moduleName
, configName
automatically.
Type: String
Default: null
These are equivalent:
const Hacker = Liftoff({
processTitle: 'hacker',
moduleName: 'hacker',
configName: 'hackerfile'
});
const Hacker = Liftoff({name:'hacker'});
Sets which module your application expects to find locally when being run.
Type: String
Default: null
Sets the name of the configuration file Liftoff will attempt to find. Case-insensitive.
Type: String
Default: null
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 working directory.
const MyApp = new Liftoff({
name: 'myapp',
extensions: {
'.js': null,
'.json': null,
'.coffee': 'coffee-script/register'
}
});
In this example, Liftoff will look for .myapp{rc}
.
const MyApp = new Liftoff({
name: 'myapp',
configName: '.myapp',
extensions: {
'rc': null
}
});
In this example, Liftoff will automatically attempt to load the correct module for any javascript variant supported by node-interpret (as long as it does not require a register method).
const MyApp = new Liftoff({
name: 'myapp',
extensions: require('interpret').jsVariants
});
Any flag specified here will be applied to node, not your program. Useful for supporting invocations like myapp --harmony command
, where --harmony
should be passed to node, not your program. This functionality is implemented using flagged-respawn. To support all v8flags, see node-v8flags.
Type: Array|Function
Default: null
If this method is a function, it should take a node-style callback that yields an array of flags.
Sets what the process title will be.
Type: String
Default: null
A method to handle bash/zsh/whatever completions.
Type: Function
Default: null
Launches your application with provided options, builds an environment, and invokes your callback, passing the calculated environment as the first argument.
const Liftoff = require('liftoff');
const MyApp = new Liftoff({name:'myapp'});
const argv = require('minimist')(process.argv.slice(2));
const invoke = function (env) {
console.log('my environment is:', env);
console.log('my cli options are:', argv);
console.log('my liftoff config is:', this);
};
MyApp.launch({
cwd: argv.cwd,
configPath: argv.myappfile,
require: argv.require,
completion: argv.completion
}, invoke);
Change the current working directory for this launch. Relative paths are calculated against process.cwd()
.
Type: String
Default: process.cwd()
Example Configuration:
const argv = require('minimist')(process.argv.slice(2));
MyApp.launch({
cwd: argv.cwd
}, invoke);
Matching CLI Invocation:
myapp --cwd ../
Don't search for a config, use the one provided. Note: Liftoff will assume the current working directory is the directory containing the config file unless an alternate location is explicitly specified using cwd
.
Type: String
Default: null
Example Configuration:
var argv = require('minimist')(process.argv.slice(2));
MyApp.launch({
configPath: argv.myappfile
}, invoke);
Matching CLI Invocation:
myapp --myappfile /var/www/project/Myappfile.js
Examples using cwd
and configPath
together:
These are functionally identical:
myapp --myappfile /var/www/project/Myappfile.js
myapp --cwd /var/www/project
These can 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
A string or array of modules to attempt requiring from the local working directory before invoking the launch callback.
Type: String|Array
Default: null
Example Configuration:
var argv = require('minimist')(process.argv.slice(2));
MyApp.launch({
require: argv.require
}, invoke);
Matching CLI Invocation:
myapp --require coffee-script/register
A function to start your application. When invoked, this
will be your instance of Liftoff. The env
param will contain the following keys:
cwd
: the current working directoryrequire
: an array of modules that liftoff tried to pre-loadconfigNameSearch
: the config files searched forconfigPath
: 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)
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();
}
});
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);
});
Emitted when Liftoff re-spawns your process (when a nodeFlag
is detected).
var Hacker = new Liftoff({
name: 'hacker',
nodeFlags: ['--harmony']
});
Hacker.on('respawn', function (flags, child) {
console.log('Detected node flags:', flags);
console.log('Respawned to PID:', child.pid);
});
Event will be triggered for this command:
hacker --harmony commmand
Check out how gulp uses Liftoff.
For a bare-bones example, try the hacker project.
To try the example, do the following:
- Install the sample project
hacker
withnpm install -g hacker
. - Make a
Hackerfile.js
with some arbitrary javascript it. - Install hacker next to it with
npm install hacker
. - Run
hacker
while in the same parent folder.