## Usage

The api has two methods that can be used. The first method is [.start](#start) and should be used in an application that runs the background script. This application is the [runner](#runner).

The second method is [.ready](#ready) and should be used inside background scripts to know when they should start executing. The runner will use `process.send` to send an `options` object to the background script. The `options` object is passed as the second argument to the callback function passed to [.ready](#ready).

The [.ready](#ready) method is not required to be used in the background script since the runner will "fire and forget" when it sends the `options` object. It's recommended to use [.ready](#ready) since it'll be easier to configure your background scripts.

### Runner

This is an example of running a background script called `my-script.js` and passing an `options` object.

```js
var background = require('{%= name %}');

// start a background script and pass options to the script
var options = { foo: 'bar' };
background.start('my-script.js', options);
```

### Script

This is an example of a background script called `my-script.js` that was passed an `options` object.

```js
var background = require('{%= name %}');

// wait for the options to be sent from the runner
background.ready(function(err, options) {
  if (err) return console.error(err);
  console.log(options);
});
```

One thing to note is that the `stdio` streams are not available in this example since the runner disconnects from the background script. To setup `stdio` streams for the background script, they may be specified on the `options` object as an array:

```js
// setup stdio streams for the background script to write to
var stdout = fs.openSync('path/to/stdout.txt', 'a');
var stderr = fs.openSync('path/to/stderr.txt', 'a');

var options = { stdio: [stdout, stderr] };
background.start('my-script.js', options);
```

See the [example](example) for more information.

## API
{%= apidocs('index.js') %}

## Acknowledgements

My main goal was to run background scripts from a parent process and still let the parent process exit before the background process finished. In researching how to achieve my goal, I learned a lot from code in [forever][] and [forever-monitor][].