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
- Create a
monitor
section in yourlaunchpad.json
(seeMonitorOptions
). - Add a list of app option objects in
monitor.apps
(seeAppOptions
). - Each app requires a
pm2
block, which requires aname
andscript
as a minimum. See PM2 docs for all supported settings. - Run
npx launchpad monitor
(ornpx 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
andstd::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 thelogToStdOut
setting. This is set totrue
by default and can otherwise be configured insettings.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
|