https://github.com/fabiospampinato/monex
Execute a script and restart it whenever it crashes or a watched file changes.
https://github.com/fabiospampinato/monex
cli execute monitor reload restart tiny watch
Last synced: 5 months ago
JSON representation
Execute a script and restart it whenever it crashes or a watched file changes.
- Host: GitHub
- URL: https://github.com/fabiospampinato/monex
- Owner: fabiospampinato
- License: mit
- Created: 2021-05-13T11:57:58.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2023-09-24T16:28:49.000Z (over 1 year ago)
- Last Synced: 2024-11-06T15:59:56.441Z (6 months ago)
- Topics: cli, execute, monitor, reload, restart, tiny, watch
- Language: TypeScript
- Size: 60.5 KB
- Stars: 16
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
README
# Monex
Execute one or multiple scripts, interactively or in daemon mode, individually or in cluster mode, and restart them whenever they crash or a watched file changes.
## Features
This is basically a lightweight all-in-one alternative to [`nodemon`](https://github.com/remy/nodemon), [`concurrently`](https://github.com/kimmobrunfeldt/concurrently) and to some extent even [`pm2`](https://github.com/Unitech/pm2).
- **Much simpler**: Compared to those libraries Monex is much much simpler, both in terms of implementation and API surface, while for a lot of use cases being just as powerful as they are.
- **Much smaller**: Compared to those libraries Monex requires ~38MB fewer code to be installed for it to work (~40MB vs ~2MB, and most of that is just readmes and stuff), which from a security perspective is a nice feature if you need to install this on a sensitive machine, like your personal machine or a server.
- **Better watching**: This library uses [`watcher`](https://github.com/fabiospampinato/watcher) for watching the filesystem instead of [`chokidar`](https://github.com/paulmillr/chokidar), meaning it handles more filesystem issues that may potentially arise and it can natively watch paths recursively under Windows.
## Install
```sh
npm install --save-dev monex
```
## Usage
You can use Monex either from the command line or programmatically, in interactive mode or in daemon mode.
### Usage - Interactive
Interactive mode means that scripts don't run in the background and won't survive terminating the current process.
#### Command Line
You would usually run the `monex` command from a `package.json` script, but you can also call `npx monex` manually.
The command has the following interface:
```sh
monex --name foo --watch pathToWatch --ignore globToIgnore --exec 'script to execute'
```
- `-c`, `--cluster`
- It's optional.
- The number of processes to execute the script in, 1 by default.
- This option is advanced, and mainly intended for clustering Node servers in daemon mode.
- `-d`, `--delay`
- It's optional.
- The minimum delay between restarts, 1000ms by default.
- `-n`, `--name`:
- It's optional.
- It provides a name to use for debugging purposes.
- You can provide multiple names if you are executing multiple scripts, one for each script, by writing multiple names after `--name` or by using the option multiple times.
- `-r`, `--restart`:
- It's optional.
- You pass it the name of the script to restart when restarting manually.
- By default all scripts are restarted when restarting manually.
- `-w`, `--watch`:
- It's optional.
- It supports either relative or absolute paths.
- You can watch multiple paths by writing multiple paths after `--watch` or by using the option multiple times.
- Remember to quote paths containing whitespaces or they will be interpreted as multiple paths, e.g. `'./path/to/my nice script.js'`.
- `-i`, `--ignore`:
- It's optional.
- Globs are matched against absolute paths pointing to watched files and folders.
- Globs interally are parsed using [`zeptomatch`](https://github.com/fabiospampinato/zeptomatch).
- You can use multiple ignore globs by writing multiple globs after `--ignore` or by using the option multiple times.
- Remember to quote globs otherwise they might get expanded by your shell, e.g. `'**/node_modules/**'`.
- `-x`, `--exec`:
- It's required.
- You pass it a full-blown shell script to execute, with no magic behind it, just write the full script you want to execute.
- You can execute multiple scripts by writing multiple scripts after `--exec` or by using the option multiple times.
- When executing multiple scripts names, watch paths, and exec commands are grouped by index and executed in groups.
- A shorthand notation for running NPM scripts is supported, e.g. `npm:foo` gets expanded automatically to `npm run foo`.
- Remember to write the full script, e.g. `node path/to/script.js`.
- Remember to quote the full script if it contains any whitespaces, e.g. `--exec 'node path/to/script.js'`.
If you want to restart the script(s) manually just send `rs` in the terminal.
That's it, super simple, there's very little to remember.
#### Programmatic API
You can also instantiate Monex programmatically, the API is essentially the same as the one exposed by the CLI.
```ts
import monex from 'monex';
const controller = monex ({
name: ['foo'],
watch: ['dist'],
ignore: ['**/.git/**'],
script: ['node path/to/script.js']
});
// Provided APIs for manually controlling the script
controller.start (); // Start the script (started by default)
controller.stop (); // Stop the script
controller.restart (); // Restart the script
controller.stat (); // Retrieve an object containing some useful monitoring stats
```
### Usage - Daemon
Daemon mode means that scripts run in the background and will survive terminating the current process.
#### Command Line
You would usually run the `monex-daemon` command, or `monexd` for short, from a `package.json` script, but you can also call `npx monex-daemon` manually.
##### Configuration
First of all a JSON configuration file containing an array with the following interface is needed:
```ts
type Config = [ // Array of script options to execute
{ // Options for a script to execute
color?: 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan',
name?: string,
watch?: string[],
cluster: 0,
delay?: number,
ignore?: string[],
exec: string
},
{ // Options for another script to execute
// ...
}
// ...
]
```
- `color`:
- It's an optional color assigned to the script, if not provided one will be selected automatically.
- `name`:
- It's an optional name assigned to the script, if not provided one will be inferred automatically.
- `watch`:
- It works just like the `watch` option in the interactive API.
- `cluster`:
- It works just like the `cluster` option in the interactive API, `0` for auto, `1` by default.
- `delay`:
- It works just like the `delay` option in the interactive API.
- `ignore`:
- It works just like the `ignore` option in the interactive API.
- `exec`:
- It works just like the `exec` option in the interactive API.
##### Commands
Various sub-commands are provided by the `context-daemon` command for managing the daemon.
###### `start`
The start command starts a daemon with the provided configuration.
If an existing daemon is found that's terminated automatically before starting the new one.
```
monex-daemon start --config path/to/config.json
monex-daemon start
```
- `-c`, `--config`:
- It's optional.
- It's a path to the JSON file containing the configuration to load.
- If it's not present Monex will try to find a file named `monex.json` automatically, walking up the filesystem starting from the current directory.
###### `stop`
The stop command terminates the daemon.
```
monex-daemon stop
```
###### `ping`
The ping command just tells you if the daemon is currently alive or not.
```
monex-daemon ping
```
###### `log`
The log command outputs the stdout and stderr buffers for each script.
```
monex-daemon log --lines 50
```
- `-n`, `--lines`:
- It's optional.
- It sets the maximum number of lines to output for each buffer, older lines won't be outputted.
###### `stat`
The stat command outputs a JSON array containing monitoring stats for all the scripts.
```
monex-daemon stat --pretty
```
- `-p`, `--pretty`:
- It's optional.
- It ouputs stats in a more human-friendly way not meant for post processing.
#### Programmatic API
You can also control the daemon programmatically, the API is essentially the same as the one exposed by the CLI.
```ts
import monex from 'monex/daemon';
// Provided APIs for manually controlling the daemon
monex.start (); // Starts the daemon
monex.stop (); // Stops the daemon
monex.ping (); // Returns either "true" or "false"
monex.log (); // Returns the output of the "log" command as a string
monex.stat (); // Returns the JSON object containing monitoring stats
```
## License
MIT © Fabio Spampinato