an for processes
Last updated 5 years ago by smassa .
BSD-3-Clause · Original npm · Tarball · package.json
$ cnpm install subprocess 
SYNC missed versions from official npm registry.


subprocess is a child process management library for Node.js. It handles startup, port management, availability checking, and teardown of a series of child processes.

It's like an for processes. Note that the depedencies are registered as the property dependsOn instead of preceding elements in an array.

This project is a safe and inclusive place for contributors of all kinds. See the Code of Conduct for details.


npm install --save subprocess


var subprocess = require('subprocess');

var config = {
  processName: {
    dependsOn: ['<other proc name>', ...],  // optional dependant processes
                                            // differs from in syntax
    command: 'node',
    commandArgs: ['index.js', '%port%'],    // %port% is replaced with the port
    port: 9999,                             // omit to get a random available port
    logPath: './log/process.log',           // file path to log file for stdio
    spawnOptions: {},                       // options to pass to child_process.spawn

    verifyInterval: 100,                    // ms, default
    verifyTimeout: 3000,                    // ms, default

    // optional, defaults to checking for something listening on the port
    // called every `verifyInterval` until `verifyTimeout` or
    // the callback says it's ready
    verify: function(port, callback){
      // custom verification logic

      // `error` means to stop checking for availability
      // `isAvailable=false` means to keep checking
      // `isAvailable=true` means that the process is up and ready
      callback(error, isAvailable);

subprocess(config, function(error, processes){
  // `error` can be a custom error thrown
  // by the verify function or it can be
  // an subprocess-specific error;
  // see the errors section for more info

  processes = {
    processName: {
      rawProcess: [ChildProcess],
      baseUrl: "",
      port: 9999,
      logPath: './log/process.log',
      logHandle: [LogHandle],
      launchCommand: 'node',
      launchArguments: ['index.js', '9999'],
      workingDirectory: '~/someplace'

All processes started this way will be automatically registered to kill themselves on process.on('uncaughtException', handler).


subprocess exposes a method that can kill all of your processes for you.

subprocess(config, function(error, processes){
  if (error) throw error;

  // do some things


You don't have to use this method to kill all processes. The point of subprocess is that it will kill these for you when the main process exits. However, if you want to manage this yourself, this is how you do it.


var subprocess = require('subprocess');
var request = require('request');

var processes = {
  app: {
    dependsOn: ['service'],
    command: 'node',
    commandArgs: ['index.js', '--port=%port%'],
    port: 4500

  service: {
    command: 'node',
    commandArgs: ['service.js', '--port=%port%'],
    verify: function(port, callback){
      request('http://localhost:'+port+'/status', function(error, response, body){
        var isReady = !error && response.statusCode == 200;
        callback(null, isReady);

subprocess(processes, function(error, processes){
  if (error) {
  console.log('processes started successfully!');


command not found

When the command string is passed to the system and a NOENT error is returned, subprocess will callback with an error with message:

Unable to find <command>

process crashed

When a process started by subprocess crashes before it can be verified, subprocess will callback with an error with message:

Process <processName> crashed with code <exitCode>.
Log output (last 20 lines):

> <log output>

See the full log at: <log path>
<original error message>

process verification timeout

When a process appears to start propertly, but cannot be verified before the verifyTimeout, subprocess will callback with an error with message:

Process <processName> did not start in time.

Debug info:
* command: <command>
           <command arguments>
* cwd:     <working directory>
* port:    <port>
* timeout: <timeout>

Log output (last 20 lines):

> <log output>

See the full log at: <log path>
<original error message>

Current Tags

  • 0.3.0                                ...           latest (5 years ago)

3 Versions

  • 0.3.0                                ...           5 years ago
  • 0.2.0                                ...           5 years ago
  • 0.1.0                                ...           6 years ago
Maintainers (1)
Today 0
This Week 0
This Month 2
Last Day 0
Last Week 2
Last Month 1
Dependencies (4)
Dev Dependencies (3)
Dependents (1)

Copyright 2014 - 2016 © |