npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

minimal-process-manager

v1.2.1

Published

A lightweight Node.js process manager: restart on crash, cluster mode, watch/cron, env, logs, and a PM2-style process list

Readme

Minimal Process Manager

A lightweight Node.js process manager: start a script, restart it on crash, optional cluster mode, pass args to the script, and control processes with stop / list / logs.

Install

npm install -g minimal-process-manager

From this repo:

npm install
node src/index.js start <script>

Quick start

# start (restarts on crash up to 5 times)
minimal-process-manager start script.js

# pass flags to the script (after --)
minimal-process-manager start app.js -- --port 3000

# name it, then manage from another terminal
minimal-process-manager start script.js --name api
minimal-process-manager list
minimal-process-manager logs api -f
minimal-process-manager stop api

Commands

| Command | Description | | ------- | ----------- | | start <script> [args...] | Start and supervise a script | | stop [name] | Stop by name, or the only running process if there is just one | | stop --all | Stop every managed process | | stop --delete | Also remove the registry entry after stop | | delete <name> | Remove a stopped/errored registry entry | | delete --all | Remove every non-running registry entry | | list | PM2-style table: uptime, restarts, mem, mode, status | | logs [name] | Show recent log lines (-n <lines>, default 50) | | logs [name] -f | Follow log output |

Exit codes

| Code | Meaning | | ---- | ------- | | 0 | Success | | 1 | General error | | 2 | Usage / invalid options | | 3 | Not found (script, process, log, path) | | 4 | Name already running | | 5 | Cannot resolve runtime / interpreter |

start options

Options belong to start (not the root program), so this works:

minimal-process-manager start script.js --cluster --cpus 2

| Option | Description | | ------ | ----------- | | --cluster | Run master + workers (default: one worker per CPU) | | --cpus <n> | Number of workers (>= 1). Requires --cluster | | --unlimited <ms> | Unlimited crash restarts; wait <ms> (>= 0) before each retry | | --name <name> | Name for stop / list / logs (default: script basename) | | --cwd <path> | Working directory for the child | | --env KEY=VALUE | Set env var (repeatable; overrides --env-file) | | --env-file <path> | Load KEY=VALUE lines from a file | | --interpreter <name> | Force runtime: node, python, bun, … | | --max-memory <mb> | Restart when child RSS exceeds <mb> MB (complements the memory meter) | | --watch [path] | Restart on file change (default: the script path) | | --cron <expr> | Restart on cron (min hour dom month dow, e.g. 0 * * * *) | | --log-date-format <fmt> | Prefix log lines (YYYY-MM-DD HH:mm:ss, tokens: YYYY MM DD HH mm ss SSS) | | --max-log-size <mb> | Rotate the log to .log.1 when it exceeds <mb> MB |

--watch / --cron are single-mode only (not with --cluster).

Script arguments

Anything after -- is forwarded to the script:

minimal-process-manager start app.js -- --port 3000 --env production
node src/index.js start examples/index.js -- --port 3001

Single process

minimal-process-manager start script.js
minimal-process-manager start script.js --unlimited 1000
minimal-process-manager start script.js --unlimited 0   # retry immediately, still unlimited
minimal-process-manager start script.js --max-memory 200 --name api
minimal-process-manager start script.js --cwd ./app --env NODE_ENV=production
minimal-process-manager start script.py --interpreter python --name py
minimal-process-manager start script.js --watch --log-date-format "YYYY-MM-DD HH:mm:ss"

Cluster mode

minimal-process-manager start script.js --cluster
minimal-process-manager start script.js --cluster --cpus 2
minimal-process-manager start script.js --cluster --cpus 2 --unlimited 2000

Workers are independent copies of your script. The manager does not share a listen port. Binding the same port in every worker (e.g. :3000) causes EADDRINUSE. Use different ports or an app built for Node cluster port sharing.

Worker stdout/stderr is collected by the master (silent workers) and printed with [worker#N:pid=…] prefixes so concurrent workers do not scramble an inherited TTY.

Runtimes

Resolution order:

  1. --interpreter — forced command (node, python/python3, bun, …)
  2. Shebang — e.g. #!/usr/bin/env python3, #!/bin/bash
  3. Extension — .js / .cjs / .mjs → node, .py → python3, .sh / .bash → bash, .rb → ruby, .pl → perl
  4. Executable — run the file directly if the executable bit is set

Otherwise start exits with code 5.

Process registry

Each start registers a named process under ~/.minimal-process-manager/ (override with MPM_HOME):

| Path | Contents | | ---- | -------- | | processes/<name>.json | PID, script, args, mode, status, restarts, … | | logs/<name>.log | Child stdout/stderr (prefixed; optional date + rotation) |

Registry fields used by list:

| Field | Description | | ----- | ----------- | | status | online / stopped / errored | | restarts | Crash / memory / watch / cron restart count | | unstable_restarts | Restarts where uptime was under 15s | | childPid | Current child PID (for memory column) | | mode | fork / cluster / watch / cron |

Stopped and errored entries stay in the registry until delete (or stop --delete). A new start with the same name replaces them.

minimal-process-manager start examples/index.js --name api
minimal-process-manager list
minimal-process-manager logs api
minimal-process-manager logs api -n 100
minimal-process-manager logs api -f
minimal-process-manager stop api
minimal-process-manager delete api
minimal-process-manager stop --all

Behavior

| Topic | Detail | | ----- | ------ | | When it restarts | Crash (code !== 0 or signal), --max-memory, --watch, or --cron | | Clean exit 0 | No restart; status → stopped | | Single mode | Max 5 crash/memory restarts, or --unlimited <ms> with no cap | | Unstable | Restart with uptime under 15s increments unstable_restarts | | Cluster mode | Master replaces crashed workers up to 5 times total, or unlimited with --unlimited <ms> | | Shutdown | SIGINT / SIGTERM or stop: SIGTERM → wait up to 5s → SIGKILL if still alive | | Memory | Single mode: 1s RSS/VSZ meter from /proc/<pid>/status (Linux); --max-memory kills + restarts when over cap | | Logs | Optional --log-date-format; optional --max-log-size rotation to .log.1 | | Log prefixes | [manager], [master], [worker#N:pid=P], [worker#N:pid=P:child:PID] |

How to test

Use a dedicated MPM_HOME so demos do not touch ~/.minimal-process-manager. Run start in the background (&) or in a second terminal; use list / logs / stop from another shell with the same MPM_HOME.

cd /path/to/minimal-process-manager
export MPM_HOME=/tmp/mpm-demo
rm -rf "$MPM_HOME"

If a demo is left running: node src/index.js stop --all, or pkill -f "src/index.js start".

1. Registry, list, and exit codes

# exit 2 = usage, 3 = not found
node src/index.js start; echo $?
node src/index.js start /no/such.js; echo $?

printf 'console.log("hi", process.env.FOO); setInterval(() => {}, 1e9)\n' > /tmp/mpm-hi.js
node src/index.js start /tmp/mpm-hi.js --name hi --env FOO=bar --cwd /tmp \
  --log-date-format "YYYY-MM-DD HH:mm:ss" &

sleep 1
node src/index.js list
node src/index.js logs hi -n 5
node src/index.js stop hi
node src/index.js list          # status=stopped
node src/index.js delete hi

Expect a PM2-style table (id, name, mode, pid, status, restarts, unstable, uptime, mem) and dated log lines.

2. --max-memory (restart when over the cap)

printf 'const a = []; while (a.length < 40) a.push(Buffer.alloc(1024 * 1024)); console.log("ok", a.length); setInterval(() => {}, 1e9)\n' > /tmp/mpm-mem.js
node src/index.js start /tmp/mpm-mem.js --name mem --max-memory 20 --unlimited 500 &

sleep 3
node src/index.js list          # restart count > 0
cat "$MPM_HOME/processes/mem.json"   # lastRestartReason: "memory"
node src/index.js stop mem --delete

3. --watch (restart on file change)

printf 'console.log("v1"); setInterval(() => {}, 1e9)\n' > /tmp/mpm-watch.js
node src/index.js start /tmp/mpm-watch.js --name w --watch /tmp/mpm-watch.js &

sleep 1
printf 'console.log("v2"); setInterval(() => {}, 1e9)\n' > /tmp/mpm-watch.js
sleep 1
node src/index.js logs w -n 10  # v1 then v2
node src/index.js list          # mode=watch, restarts >= 1
node src/index.js stop w --delete

4. --env-file and --interpreter

printf 'X=1\nY=2\n' > /tmp/mpm.env
printf 'console.log(process.env.X, process.env.Y); setInterval(() => {}, 1e9)\n' > /tmp/mpm-env.js
node src/index.js start /tmp/mpm-env.js --name env --env-file /tmp/mpm.env --env Y=9 --interpreter node &

sleep 1
node src/index.js logs env -n 3   # prints: 1 9
node src/index.js stop env --delete

5. Crash restarts and counters

node src/index.js start examples/crash.js --name crash --unlimited 300 &

sleep 2
node src/index.js list            # restarts and unstable climbing
cat "$MPM_HOME/processes/crash.json"
node src/index.js stop crash --delete

6. --cron (optional; waits for the next minute)

# restart every minute at second 0
node src/index.js start /tmp/mpm-hi.js --name cron --cron "* * * * *" &
# wait ~1 minute, then:
node src/index.js list
node src/index.js logs cron -n 20
node src/index.js stop cron --delete

7. Cluster mode

node src/index.js start examples/crash.js --cluster --cpus 2 --unlimited 1000 --name chello &

sleep 1
node src/index.js list            # mode=cluster/2
node src/index.js logs chello -n 20
node src/index.js stop chello --delete

8. HTTP demo (single mode only)

node src/index.js start examples/index.js --name api -- --port 3001 &
# other terminal (same MPM_HOME):
node examples/call.js
node src/index.js list
node src/index.js stop api --delete

Prefer examples/crash.js for cluster tests: examples/index.js binds one port and will conflict across workers.

Examples (repo)

| File | Useful for | Notes | | ---- | ---------- | ----- | | examples/crash.js | Restarts, --unlimited, --cluster, --cpus, counters | Best file to validate manager behavior | | examples/index.js | Single mode, memory meter, HTTP | Accepts --port <n> (default 3000). Avoid with --cluster (port conflict) | | examples/call.js | Optional traffic against the HTTP demo | Only useful while examples/index.js is running |

npm scripts

| Script | Command | | ------ | ------- | | npm run start:example | single process, examples/index.js | | npm run start:cluster | cluster + examples/index.js (expect port conflicts; prefer crash.js for cluster tests) | | npm run start:unlimited | single process, --unlimited 1000 |

License

Apache-2.0