Using ShellJS Plugins

Using an existing plugin (list)

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](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.