Process Manager & Builder

Behind the scenes, the Boilerplate uses a highly optimized programmatic approach to build, bundle, and serve your application. Rather than relying on simple npm scripts hitting global CLI tools, the deployment logic is controlled via TypeScript.

All DevOps commands reside in src/commands/.

Architecture Flow

Press enter or space to select a node. You can then use the arrow keys to move the node around. You can then use the arrow keys to move the node around, press delete to remove it and press escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or press escape to cancel.

---

1. The TSUP Dynamic Builder (exec-builder.ts)

Instead of compiling the entire src/ directory verbatim, the project uses a smart compiler built on top of the TypeScript Compiler API (ts.createProgram) and tsup (esbuild).

How it works

When you build the project for production, exec-builder.ts:

1. Reads the entry points defined in your PM2 Workspace (e.g., the HTTP server and the WebSocket server).
2. Walks the AST (Abstract Syntax Tree) of your code to discover exactly which files are imported.
3. Ignores files that are never imported (Dead Code Elimination at the project scope).
4. Bundles and Minifies the exact dependency tree into optimized esm files inside /dist, dropping development layers and applying .env specific tweaks.

---

2. Programmatic Process Management

The project controls PM2 via its Node.js API (pm2-workers.ts), rather than using the ecosystem.config.js file common in legacy projects. This allows dynamic adjustments based on the runtime (Bun vs Node).

The Workspace (pm2-workspace.ts)

This file is the single source of truth for the services that run on your server.

export default (<worker[]>[
	{
		activated: true,
		group: "primary",
		name: "primary-webserver",
		tsx: "./src/functions/http-primary-webserver.ts", // Dev Entry
		bun: "./dist/functions/http-primary-webserver.js", // Prod Entry
        // ... configs
		heartbeat: `${env.UPTIME_SERVER}:${env.UPTIME_PORT}/api/push/xyVlTFF...`,
	}
]);

Each "worker" defines an entry point. You can add more workers here, such as a dedicated RabbitMQ consumer or a background Cron job instance.

Development vs Production Mode

The pm2-workers.ts script automatically detects your environment:

• Development (dev): PM2 is bypassed. The script uses native Node spawn() to launch bun --watch or tsx watch, attaching directly to stdio for instant console feedback.
• Production: It connects to the local PM2 daemon, forks the processes using bun as the interpreter, and begins monitoring.

Remote Control & Uptime Kuma

The programmatic PM2 integration includes two advanced features:

1. Heartbeat/Uptime Kuma: When a worker starts successfully on production, it can fire a fetch() request to an external Uptime Kuma push URL, confirming the node is completely alive.
2. Distributed Restart: The PM2 script subscribes to Redis pub/sub (workers:server:restart). This means you can trigger an internal API that publishes to Redis, and PM2 will gracefully restart specific workers across the system without touching the terminal.