Modules

pboss supports a plugin system for extending functionality.

pboss module install#

Install a module from a git URL, local path, or npm package name:

pboss module install https://github.com/user/pboss-logrotate.git
pboss module install ./my-pboss-module
pboss module install pboss-prometheus-pushgateway

pboss module list#

List installed modules:

pboss module list

pboss module uninstall#

Remove an installed module:

pboss module uninstall pboss-prometheus-pushgateway

Writing a pboss module#

A pboss module is a package with a default export implementing the PBossModule interface:

// my-module/index.ts
import type { ProcessManager } from "pboss";

export default {
  name: "my-module",
  version: "1.0.0",

  init(pm: ProcessManager) {
    console.log("[my-module] Initialized with", pm.list().length, "processes");
  },

  destroy() {
    console.log("[my-module] Destroyed");
  },
};

• init runs when the daemon loads the module — receive the ProcessManager instance and hook into the lifecycle.
• destroy runs on daemon shutdown — close sockets, flush buffers, stop timers.

The ProcessManager instance exposes the same operations as the CLI: list, start, stop, restart, reload, scale, logs, and more. See the programmatic API for the full surface — a module is just code running inside the daemon with that API in hand.

Reacting to events#

Since issue #32, the pm handed to init(pm) is a real event source: it extends EventEmitter, so modules react the instant something happens instead of polling pm.list() on a timer. Every daemon-side transition fires a typed process:* event — including autonomous ones a module could never see before: crash autorestarts, maxMemoryRestart trips, file-watch restarts, cron restarts, and health-check restarts.

// crash-shipper/index.ts — a module that reacts instantly
import type { ProcessManager } from "pboss";

export default {
  name: "crash-shipper",
  version: "1.0.0",

  init(pm: ProcessManager) {
    pm.on("process:crashed", (e) => {
      ship("crash", e.process.name, e.exitCode ?? e.exitSignal);
    });
    pm.on("process:restart", (e) => {
      ship("restart", e.process.name, e.source); // user|crash|memory|watch|cron|health
    });
    pm.on("process:errored", (e) => {
      ship("gave-up", e.process.name, e.reason);
    });
  },

  destroy() { /* off() your listeners here */ },
};

The keys are process:start, process:stop, process:restart, process:crashed, process:errored, process:delete, and process:reload. Payloads are the same PbossProcessEvent objects the client API emits — see Events for the full shape. Listener errors are caught and recorded, so a buggy module can never take down the supervisor’s exit paths.