Using ShellJS Plugins

Nate Fischer edited this page Jul 1, 2018 · 12 revisions

Using an existing plugin

Using ShellJS plugins is very easy! To use shelljs-plugin-foo, follow these steps:

Save the package

$ npm install --save shelljs
$ npm install --save shelljs-plugin-foo

Load the plugin

// index.js
// Require all ShellJS plugins first
require('shelljs-plugin-foo');

// Require ShellJS itself
var shell = require('shelljs'); // 'shelljs/global' is allowed instead

// Require any other packages you like

var ret = shell.foo(); // this function works!
shell.echo(ret.stdout); // most plugins return a ShellString, just like ShellJS commands!
shell.foo().grep('o').sed(/o/g, 'a'); // most plugins will be fully pipe-able

Writing a plugin

Disclaimer: this API is not yet stable, and it's likely to change a bit

Naming

We recommend the following format: shelljs-plugin-<your command name>. If you're writing a git plugin, you'd name it shelljs-plugin-git.

package.json

The most important thing is to require the most recent version of ShellJS as a peer-dependency. If you want to add unit tests for your plugin as well, you'll probably want it as a dev-dependency too:

{
  "name": "shelljs-plugin-foo",
  "version": "0.1.0",
  "description": "A foo plugin for ShellJS",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [
    "shelljs",
    "plugin",
    "foo"
  ],
  "author": "Joe Smith",
  "license": "MIT",
  "devDependencies": {
    "shelljs": "^0.7.3"
  },
  "peerDependencies": {
    "shelljs": "^0.7.3"
  }
}

Boilerplate

Create a file named index.js and start hacking away! You'll need to implement your command as a JavaScript function, and then register that command with ShellJS. Here's an example:

// This exposes the plugin utilities
var plugin = require('shelljs/plugin');

// Require whatever modules you need for your project here

// Implement your command in a function, which accepts `options` as the
// first parameter, and other arguments after that
function fooImplementation(options, fileName) {
  return 'Hello world';
}

// Register the new plugin as a ShellJS command
plugin.register('foo', fooImplementation, {
  cmdOptions: {},   // There are no supported options for this command
});

// Optionally, you can export the implementation of the command like so:
exports.foo = fooImplementation;

plugin.register() options

plugin.register() can take a few different options. In the example above, we use the cmdOptions attribute. For the list of available options, check out the source code (note: this is subject to change until the API is officially released).

Look at this file to see some options in action.

TODO: once the API stabilizes, we'll add an actual table of options, defaults, and their meanings.

Option Type Default Meaning
allowGlobbing Boolean true Should arguments be automatically glob-expanded?
canReceivePipe Boolean false Can this command handle piped input?
cmdOptions Object/null null An object specifying the command's allowed options. If null, no option parsing will happen (the options string will be passed bare to your command). If {}, then no options will be allowed (and the first parameter your command receives will always be {}). Otherwise, the options-string will be parsed such that cmdOptions: { '-f': 'foo' } will result in your function receiving { foo: true } or { foo: false }, depending on if -f was specified.
globStart Number (int) 1 The first argument to glob-expand (all arguments following this will also be glob-expanded)
pipeOnly Boolean false Should this command only be allowed on the right-hand-side of pipes (e.g. tr)?
wrapOutput Boolean true Should output be wrapped as a ShellString() object?

README badge

You should now have a functioning shelljs-plugin! Feel free to use the following README badge:

shelljs-plugin

[![shelljs-plugin](https://img.shields.io/badge/shelljs-plugin-brightgreen.svg?style=flat-square)](https://github.com/shelljs/shelljs/wiki/Using-ShellJS-Plugins)

Also, feel free to add your plugin to the list of available plugins.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.