Bundle and execute exec files.
npm install @todesktop/client-execBundle and execute exec files.
Install @todesktop/client-exec in your client-side application using
``sh`
npm install @todesktop/client-exec
Installation of the plugin package is also necessary. Using the ToDesktop Builder interface, navigate to Plugins. Click on the Explore button for "File Exec" and install the package.
Listen to debug, stdout, stderr, or exit events from your executable.
`js
import { subscribe } from "@todesktop/client-exec";
subscribe((message) => {
if (message.type === "debug") {
// todesktop process log
} else if (message.type === "stdout") {
// stdout from executable
} else if (message.type === "stderr") {
// stderr from executable
} else if (message.type === "exit") {
// process exited - message.code and message.signal available
console.log("Process exited with code:", message.code, "signal:", message.signal);
}
});
`
The exit event provides structured data about how the process terminated:
- message.code: The exit code (number) if the process exited normally, or null
- : The signal name (e.g., "SIGTERM", "SIGKILL") if the process was killed, or null
Common exit scenarios:
| Scenario | code | signal |
|----------|------|--------|
| Clean exit | 0 or null | null |null
| Error exit | Non-zero number | |null
| Terminated by app quit | | "SIGTERM" or "SIGKILL" |null
| Manual termination | | "SIGTERM" or "SIGKILL" |
Calling execute will execute the file. Make sure to call subscribe before execution if you would like to see the execution logs. You can pass command-line arguments to your executable using an array of flags.
`js
import { execute } from "@todesktop/client-exec";
// Execute without flags
await execute();
// Execute with flags
await execute(["--version"]);
// Execute with multiple flags
await execute(["--config", "path/to/config.json", "--verbose"]);
`
Manually terminate all processes that were spawned by execute. This function waits for processes to actually terminate before returning and provides detailed results about the termination operation.
The function:
- First attempts graceful termination with SIGTERM
- Waits up to 5 seconds for processes to exit gracefully
- Forces termination with SIGKILL if processes don't respond
- Returns only after all termination attempts are complete (max ~7 seconds)
- Returns a result object with termination statistics
NOTE: This will not terminate processes that were spawned by other instances of your application which may not have quit correctly
`js
import { terminateAllProcesses } from "@todesktop/client-exec";
// Terminate all active processes
const result = await terminateAllProcesses();
// Result object structure:
// {
// terminated: 3, // Number of successfully terminated processes
// failed: 1, // Number of processes that couldn't be terminated
// errors: [ // Array of error messages for failed terminations
// "Process 2: Failed to send SIGTERM signal"
// ]
// }
if (result.failed > 0) {
console.error("Some processes could not be terminated:", result.errors);
}
`
- .pkg files are automatically opened using the open command, rather than being executed directly. This allows for the standard macOS package installation process.
- All spawned processes are automatically tracked and properly terminated when the parent application quits
- During app shutdown, processes are given 2 seconds to terminate gracefully before being force-killed
- The terminateAllProcesses() function can be used to manually terminate all running processes
- Both automatic and manual termination verify that processes actually exit before proceeding
- This prevents orphaned processes from running after the ToDesktop app is closed
- Added exit event type to subscribe() for listening to process exit events with structured data (code and signal)
- Added terminateAllProcesses() function to manually terminate all spawned processesbefore-quit
- Function waits for process termination with timeout handling
- Returns detailed results including success/failure counts and error messages
- Attempts graceful termination (SIGTERM) before forcing with SIGKILL
- Improved handler to properly wait for process termination during app shutdown
- Extracted shared termination logic for consistent behavior between manual and automatic cleanup
- Added tests for process termination and execution functionality
- Added automatic process cleanup when the parent application quits to prevent orphaned processes
- .pkg files are automatically opened using the open command, rather than being executed directly
- Added support for command-line arguments/flags in the execute` function
- Added debug logging for flag usage
- Fixed an issue where the executable would not spawn on Windows (https://github.com/nodejs/node/issues/52554)