node-ipcmain documentation · JavaScript: Node.js only

Two required methods

Parser contract

Use a built-in parser for the official profiles, opt into the ecosystem compatibility parser, or provide one direct custom class or object. Parser selection and method binding happen once.

Parser subpaths remain Node.js-only.

node-ipc/parsers and node-ipc/parsers/message share the package's Node defaults and Buffer-based transport contract. They do not run in web browsers, whether bundled or unbundled.

Official exports

import {
  RawParser,
  FastParser,
  GuardedParser,
  AssuredParser,
  IPCProtocolError
} from 'node-ipc';

import {
  createParser,
  reservedEventTypes
} from 'node-ipc/parsers';
ExportContract
RawParserBuffer pass-through and no node-ipc framing.
FastParser / ParserDirect JSON event envelopes separated by the configured delimiter.
GuardedParserFast plus bounded frames and stream writes, envelope and name controls, and incomplete-frame timing.
AssuredParserGuarded plus a required event allow-list; the client/server runtime adds mutual-TLS or secure-local-server-root startup gates.
IPCProtocolErrorA receive-path protocol failure published as error. Streams close; UDP peer frame state resets.
createParser(config)Resolves the configured built-in, class, or object and checks the two required methods once.

Custom class or object

class ApplicationParser {
  constructor(config) {
    this.delimiter = config.delimiter;
  }

  encode(type, data) {
    // Return a string, Buffer, or Uint8Array accepted by the socket.
    return encodeApplicationFrame(type, data);
  }

  read(remainder, chunk, receive) {
    // Call receive({type, data}) once for every complete message.
    // Return only the unconsumed remainder for the next chunk.
    return decodeApplicationFrames(remainder, chunk, receive);
  }
}

ipc.config.parser = ApplicationParser;
// An already-created ApplicationParser object is also accepted.
MemberRequiredMeaning
encode(type, data)YesProduces the outbound wire value without node-ipc wrapping it again.
read(remainder, chunk, receive)YesConsumes complete frames, emits {type, data} objects in order, and returns the remaining partial frame.
rawNoWhen true, incoming Buffers go straight to data and read() is not on the receive path.
maxPendingBytesNoA positive finite byte limit selects the bounded stream-write handler once.
messageTimeoutNoA truthy millisecond value selects incomplete-frame timing once.
The custom parser owns its checks.

node-ipc does not layer Guarded validation around a custom parser. Validate framing, envelope shape, event names, sizes, and state directly if the trust boundary requires them. Throw IPCProtocolError for a receive-path violation that should publish error; stream failures close, while UDP peer frame state resets.

A parser class is constructed for each client/server. A parser object is used as supplied and may be shared if the same config object creates several endpoints; provide separate objects or keep it stateless.

js-message compatibility

import MessageParser from 'node-ipc/parsers/message';

ipc.config.parser = MessageParser;

This official subpath preserves an ecosystem integration without putting js-message on the default path. It is explicit opt-in compatibility behavior: malformed envelopes become a message whose type is error. It is not a hardened decoder and does not add Guarded or Assured controls.

Use it when that behavior is part of the application contract. Use Guarded or Assured when you need node-ipc protocol containment, or extend an official parser when you need both compatibility and a reviewed policy.

Wire and transport notes

Compare profilesSecurity boundaryTest inventory
← Runtime profilesAPI reference →