README.md

Launchpad Monitor

The @bluecadet/launchpad-monitor package launches and monitors any number of apps.

Under the hood, it uses PM2 for process management, and adds a few features like window foregrounding and minimizing.

Configuration

1. Create a monitor section in your launchpad.json (see MonitorOptions).
2. Add a list of app option objects in monitor.apps (see AppOptions).
3. Each app requires a pm2 block, which requires a name and script as a minimum. See PM2 docs for all supported settings.
4. Run npx launchpad monitor (or npx launchpad to update content first if configured)

{
  "monitor": {
    "apps": [
      {
        "pm2": {
          "name": "my-app",
          "script": "my-app.exe"
        }
      }
    ]
  }
}

Apps will be relaunched individually as soon as they exit.

MonitorOptions

Top-level options of Launchpad Monitor.

Property	Type	Default	Description
apps	Array.<AppOptions>	[]	A list of AppOptions to configure which apps to launch and monitor.
deleteExistingBeforeConnect	boolean	false	Set this to true to delete existing PM2 processes before connecting. If you're running volatile apps or your node process might be quit unexpectedly, this can be helpful to start with a clean slate on startup.
windowsApi	WindowsApiOptions		Advanced configuration for the Windows API, e.g. for managing foreground/minimized/hidden windows.

AppOptions

Options for an individual app to monitor.

Property	Type	Default	Description
pm2	pm2.StartOptions	null	Configure which app to launch and how to monitor it here. See: https://pm2.keymetrics.io/docs/usage/application-declaration/#attributes-available
windows	WindowOptions	new WindowOptions()	Optional settings for moving this app's main windows to the foreground, minimize or hide them.
logging	AppLogOptions	new AppLogOptions()	Optional settings for how to log this app's output.

WindowOptions

Options for how an app's windows should be managed.

Property	Type	Default	Description
foreground	boolean	false	Move this app to the foreground once all apps have been launched.
minimize	boolean	false	Minimize this app's windows once all apps have been launched.
hide	boolean	false	Completely hide this app's windows once all apps have been launched. Helpful for headless apps, but note that this might cause issues with GUI-based apps.

Example: Monitor Two Apps

The following launchpad.json will launch and monitor two apps. The first app window will be foregrounded after launch, the second app will be minimized. If any of the apps exit, PM2 will relaunch them.

{
  "monitor": {
    "apps": [
      {
        "pm2": {
          "name": "main-app",
          "script": "my-main-app.exe",
          "cwd": "../apps/"
        },
        "windows": {
          "foreground": true
        }
      },
      {
        "pm2": {
          "name": "side-app",
          "script": "my-side-app.exe",
          "cwd": "../apps/",
          "args": "--custom-arg=true"
        },
        "windows": {
          "minimize": true
        }
      }
    ]
  }
}

Logging App Output

To capture your apps' logs in Launchpad Monitor you need to ensure that your apps are routing them to stdout and stderr.

Unity

To redirect Unity's logs to stdout and stderr, launch your app using the -logfile - argument:

{
  "monitor": {
    "apps": [
      {
        "name": "unity-app",
        "script": "UnityPM2Test.exe",
        "args": "-logfile -"
      }
    ]
  }
}

Cinder

• Cinder doesn't route logs directly to std::cout and std::cerr by default, so this has to be done manually. See here for an example for how to create one, and here for how to add it.
• If you use Cinder-BluecadetViews, all logs are routed to stdout/stderr via the logToStdOut setting. This is set to true by default and can otherwise be configured in settings.json or via cli flag: my-app.exe console=false logToStdOut=true

Adanced Configuration

See below for further settings that can be configured globally and on a per-app level.

WindowsApiOptions

Global options for how window order should be managed.

Property	Type	Default	Description
nodeVersion	string	'>=17.4.0'	The minimum major node version to support window ordering. Node versions < 17 seem to have a fatal bug with the native API, which will intermittently cause V8 to crash hard. See: node-ffi-napi/ref-napi#54 (comment)
debounceDelay	number	3000	The delay until windows are ordered after launch of in ms. If your app takes a long time to open all of its windows, set this number to a higher value to ensure it can be on top of the launchpad terminal window. Keeping this high also reduces the CPU load if apps relaunch often.

AppLogOptions

Options for how an app's logs should be saved, routed and displayed.

Property	Type	Default	Description
logToLaunchpadDir	boolean	true	Route application logs to launchpad's log dir instead of pm2's log dir.
mode	'bus' | 'file'	'bus'	How to grab the app's logs. Supported values: - 'bus': Logs directly from the app's stdout/stderr bus. Can result in interrupted logs if the buffer isn't consistently flushed by an app. - 'file': Logs by tailing the app's log files. Slight lag, but can result in better formatting than bus. Not recommended, as logs cannot be rotated by launchpad.
showStdout	boolean	true	Whether or not to include output from stdout
showStderr	boolean	true	Whether or not to include output from stderr