Performance

Built-in Clustering

Use every core with one configuration key. MoroJS picks the transport: worker threads on the native engine, worker processes everywhere else.

Overview

A single Node.js event loop uses one core. Clustering runs several copies of your app, each accepting connections on the same port, so the kernel spreads traffic across cores. MoroJS does this for you: no cluster.fork() in your code, no separate entry script, no process manager required.

Hand-rolled clustering

  • cluster.fork() boilerplate in every entry file
  • Workers that die silently
  • Background jobs running once per worker
  • One transport, chosen for you by the runtime

With MoroJS

  • performance.clustering: { enabled: true }
  • Crashed workers restarted with backoff
  • Jobs and gRPC run once, in the primary
  • Worker threads or processes, picked automatically

How It Works

With the native engine (@morojs/engine 1.1.6 or newer) on macOS and Linux, the workers are worker threads inside one process. Each thread runs its own copy of the app and its own engine, and binds the port with SO_REUSEPORT so the kernel balances accepted connections across them. One process means the Node binary, the engine and the compiled code are shared, so memory per worker drops, there is one pid to supervise, and a worker that throws is an event on the primary rather than a process death.

Everywhere threads cannot work, the same configuration runs worker processes through node:cluster, exactly as before: on Windows (no SO_REUSEPORT), with engine: 'node', with an engine older than 1.1.6, or if a worker thread fails to boot. The log line at startup says which transport is in use.

Two things to keep in mind with threads: your entry script's module scope runs once per worker inside the same process (a forked worker process does the same), and process.chdir() is not available inside a worker thread. A native crash inside one thread ends the whole process, where processes would isolate it; the engine is fuzzed nightly and sanitizer-clean, and the process transport remains the automatic fallback.

A worker thread loads your entry file with Node's own loader. Whether a TypeScript entry started through tsx (or ts-node) gets the loader's hooks inside worker threads depends on the Node line: on Node 24.11 it does not, so those threads fail to boot and Moro falls back to worker processes for that run, with a falling back to worker processes line in the log; on Node 24.21 the hooks reach the threads and the same entry runs on threads. Both are handled without configuration. Your compiled entry (node dist/app.js) runs on threads on every supported Node.

Configuration

Enable clustering
1const app = await createApp({
2  performance: {
3    clustering: {
4      enabled: true,
5      workers: 'auto',        // or a number
6      // memoryPerWorkerGB: 2 // optional: bounds 'auto' by available RAM
7    },
8  },
9});
10
11app.listen(3000);

workers: 'auto' is min(usable CPUs, usable RAM / memoryPerWorkerGB), where memoryPerWorkerGB defaults to the RAM left after a 4 GB headroom, divided by the CPU count (never below 0.5 GB). Both counts are what the process may actually use, not the host's: a cgroup CPU quota (docker run --cpus, a Kubernetes CPU limit), the affinity mask (--cpuset-cpus) and a cgroup memory limit all bound them, so a 96-thread host pinned to 32 cores starts 32 workers. The same keys work as environment variables: CLUSTERING_ENABLED, CLUSTER_WORKERS, MEMORY_PER_WORKER_GB.

Graceful shutdown is built in: on SIGTERM or SIGINT the primary asks every worker to drain its in-flight requests, then stops its own services and exits. A second signal exits immediately.

What Runs Where

Every worker serves HTTP and WebSocket traffic, loads auto-discovered modules and file-based routes, and initialises GraphQL (it registers routes on the app). The primary runs the things that must exist exactly once per cluster: the job scheduler (leader election already treats the primary as the participant) and the gRPC server, which listens on its own port.

Per-worker state stays per worker: in-memory caches and in-memory rate-limit counters are not shared between workers, with threads or with processes. Use the store-backed variants when a limit must hold across the whole cluster.