forky

1.2.0 verified Sat May 09 auth: no javascript maintenance

Forky (v1.2.0) simplifies Node.js cluster management by automatically forking workers equal to the number of CPU cores. It auto-restarts crashed workers and supports graceful shutdown via the `suicide` flag. Unlike alternatives like `pm2` or `cluster` alone, forky is lightweight, zero-config for basic setups, and keeps the worker code unmodified. It ships TypeScript types and is suitable for Node >=8. Development appears stale (last commit 2019); no major release since.

Common errors

error Error: Cannot find module './worker.js' ↓

cause The path provided to forky is relative to the working directory, not the master script.

fix

Use __dirname + '/worker.js' or an absolute path.

error Error: listen EADDRINUSE :::8000 ↓

cause Multiple workers trying to bind to the same port; worker code should not call server.listen() directly when master forks multiple.

fix

Have each worker listen on a different port (e.g., 8000 + worker.id) or use a reverse proxy.

error TypeError: forky is not a function ↓

cause Importing the module incorrectly, e.g., using named import when only default export exists.

fix

Use import forky from 'forky' or const forky = require('forky').

Warnings

gotcha If the worker file is not found or cannot be loaded, forky will exit with an unhandled error. ↓

fix Ensure the path is absolute or resolved correctly relative to the master process.

deprecated The `suicide` property on worker objects is deprecated in Node.js and will be removed. ↓

fix Use `worker.exitedAfterDisconnect` instead.

gotcha Forky does not handle SIGTERM/SIGINT propagation; workers may not shut down cleanly on process exit. ↓

fix Implement custom signal handlers in the master process to disconnect workers.

gotcha If all workers crash immediately (e.g., due to a syntax error in worker code), forky will loop infinitely restarting them. ↓

fix Add error handling or a max restarts limit via process.on('uncaughtException') in workers.

gotcha Forky does not support IPC messaging between master and workers beyond the built-in cluster messaging. ↓

fix Use `process.send()` and `cluster.on('message')` as documented.

Install

npm install forky

yarn add forky

pnpm add forky

Imports

default
wrong
```
const forky = require('forky')
```
correct
```
import forky from 'forky'
```
CJS require works too; package supports CommonJS.
ForkyOptions
```
import type { ForkyOptions } from 'forky'
```
TypeScript type import; requires TS 3.8+
default function call
wrong
```
forky() without options
```
correct
```
import forky from 'forky';
forky({ path: './worker.js' })
```
The default export is a function that takes a ForkyOptions object.

Quickstart

Shows basic forky usage: master forking workers from a separate file, worker with HTTP server and graceful shutdown.

import forky from 'forky';
import http from 'http';

// Worker (worker.js)
const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from worker ' + process.pid);
});
server.listen(8000);

// Graceful shutdown on uncaught exception
process.on('uncaughtException', (err) => {
  console.error(err);
  process.disconnect();
});

// Master (master.js) - run with: npx ts-node master.ts
forky({ path: './worker.js' });