@flexent/ensemble

YAML-driven process manager for running multiple Node.js apps locally.

Install

npm install @flexent/ensemble

CLI

From the directory that contains ensemble.yaml:

npx ensemble

Options:

• -f, --file <path> — config file (default: ensemble.yaml in cwd)

Config

Create ensemble.yaml at the project root:

apps:
  - id: api
    dir: packages/api
    entrypoint: out/bin/run.js
    args:
      - --watch
    env:
      HTTP_PORT: "32001"
      META_HTTP_PORT: "38001"
    waitForPorts:
      - HTTP_PORT
      - META_HTTP_PORT
  - id: worker
    dir: packages/worker
    entrypoint: out/bin/run.js
    dependsOn:
      - api
    waitForPorts:
      - 39001
    env:
      SKIP_STORAGE_SETUP: "true"

sharedEnv:
  LOG_PRETTY: "true"
  REGISTRY_URL: http://localhost:32003

stopGracePeriodMs: 5000

Each app is forked with stdio: inherit. On stop, ensemble sends SIGTERM, waits stopGracePeriodMs (default 5000), then sends SIGKILL if the child is still running.

args is optional. Command-line arguments passed to the forked process after entrypoint.

stopGracePeriodMs is optional.

dependsOn lists app ids that must start before this one. Apps without dependencies start in config order. Ensemble stops apps in reverse start order.

waitForPorts lists env var names or literal port numbers. After forking, ensemble waits until each port accepts TCP connections on 127.0.0.1 before the app is considered started. Env var names are resolved from the app’s merged env (sharedEnv, then per-app env). Combine with dependsOn when a dependent should wait for a dependency to be listening.

sharedEnv is merged into each forked app’s environment. Per-app env overrides shared values. The ensemble parent process is not modified.

Programmatic API

import { Ensemble } from '@flexent/ensemble';

const ensemble = new Ensemble();
await ensemble.resolve('path/to/ensemble.yaml');
await ensemble.start('api');
await ensemble.stop('api');
// OR
await ensemble.startAll();
await ensemble.stopAll();