@bluecadet/launchpad-monitor
TypeScript icon, indicating that this package has built-in type declarations

1.8.0 • Public • Published

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: https://github.com/node-ffi-napi/ref-napi/issues/54#issuecomment-1029639256
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

Readme

Keywords

none

Package Sidebar

Install

npm i @bluecadet/launchpad-monitor

Weekly Downloads

78

Version

1.8.0

License

ISC

Unpacked Size

94 kB

Total Files

19

Last publish

Collaborators

  • baerkins
  • peteinge
  • benjaminbojko
  • claytercek
  • bluecadetreleases