Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท process

Node.js process.send() method and the message event

Reference for process.send(), process.connected, process.disconnect() and the message event in Node.js: talk to a parent process over an IPC channel.

A Node.js process started with an IPC channel (by child_process.fork(), or by spawn() with an 'ipc' entry in stdio) can exchange messages with its parent. Inside the child, process.send(message) sends a message up to the parent, and the message event on process fires for every message the parent sends down. The parent uses child.send() and child.on('message').

Messages are serialized for you (JSON by default, or the structured-clone-like 'advanced' serialization), so you can pass plain objects, arrays and numbers without any framing. When the process was not started with a channel, process.send is undefined, which is the easy way to detect it.

NODE
if (process.send) {
  process.send({ ready: true });
}
process.on('message', (msg) => { /* ... */ });

Try it

Node.js A parent and a child talking

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js No channel in this process

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
process.send(
  message: object | string | number | boolean | null,
  sendHandle?: net.Socket | net.Server,
  options?: { keepOpen?: boolean },
  callback?: (error: Error | null) => void
): boolean

process.on('message', (message, sendHandle) => { })
process.connected: boolean
process.disconnect(): void
Name Description
message The value to send. It must be serializable; functions, symbols and cyclic structures are not.
sendHandle Optional TCP socket or server to hand over to the other process.
options.keepOpen Keep the handle open in the sender after sending a socket.
callback Called after the message was sent, with an error or null.

Returns: true unless the channel's queue is backed up, in which case it returns false. The message is still queued; use the callback to pace a fast sender.

Errors / edge cases:

  • With no channel, process.send, process.disconnect, process.connected and process.channel are all undefined, so calling them throws a TypeError.
  • Sending after the channel closed emits an error event on the process (or calls the callback with ERR_IPC_CHANNEL_CLOSED), so check process.connected.
  • On the receiving side the disconnect event fires when the other end closes the channel.

Usage notes

  • Detect the channel with if (process.send) or process.connected. A script that is run both on its own and as a forked worker can behave differently in each case.
  • The child stays alive as long as the channel is open and a message listener exists. Call process.disconnect() (or remove the listener) when the conversation is finished, as the example does, or the child will not exit by itself.
  • JSON limits. With the default serialization, Map, Set, Date (becomes a string), undefined and BigInt do not survive. Fork with { serialization: 'advanced' } for structured-clone behaviour including BigInt and typed arrays.
  • Messages are asynchronous and ordered; send does not wait for the other process to handle them.
  • Large messages are slow. The channel is a pipe. For big data use files or streams on stdio.
  • For threads, not processes, use worker_threads and parentPort.postMessage(), which is faster and supports transferables.
  • Handle passing lets a parent distribute accepted TCP connections to children; the cluster module is built on this.