zeromq.js: Node.js ØMQ Bindings and Setup

What zeromq.js Adds to Node.js Messaging

zeromq.js solves the problem of using ØMQ messaging patterns from Node.js. It exposes bindings for the native ØMQ library while presenting sockets and methods through JavaScript and TypeScript APIs. The README lists `Request`, `Reply`, `Push`, `Pull`, `Publisher`, and `Subscriber` as useful socket types. These cover request-response, work distribution, and publication-subscription relationships without requiring the application to implement those patterns from ordinary TCP sockets.

The library is not a general-purpose message broker. It gives the application control over sockets, endpoints, message parts, subscription topics, and connection direction. That makes it relevant to distributed workers, service processes, event distribution, and low-level messaging experiments. It also means the developer must choose the appropriate ØMQ pattern and arrange the endpoints correctly.

The project describes its goals as semantically similar to native ØMQ while retaining JavaScript idioms. Its documented goals include `async` and `await`, async iterators, TypeScript support, Curve security through Libsodium, draft API support, and compatibility with ZeroMQ 4 and 5. The package therefore provides a native messaging layer with an asynchronous Node.js surface, not a separate service abstraction with queues and administration features.

Socket Classes and Message Flow

The central abstraction is a socket class. The README shows ES module imports such as `Request` and a namespace import through `zmq`, as well as CommonJS access through `require("zeromq")`. A socket can bind to an endpoint or connect to one. In the Push/Pull example, the producer creates a `Push` socket, binds it to `tcp://127.0.0.1:3000`, and sends work messages. The worker creates a `Pull` socket, connects to the same endpoint, and iterates over incoming messages.

The receiving side uses `for await` to consume the socket. The callback receives an array of message parts, so the example destructures the first part with `[msg]`. Multipart messages also appear in the Publisher and Subscriber example. A publisher sends `["kitty cats", "meow!"]`, while the subscriber receives `[topic, msg]`. The subscriber calls `subscribe("kitty cats")`, which selects the documented topic filter for that socket.

The Request and Reply example follows a request-response flow. A `Request` socket connects, sends `"4"`, and awaits `sock.receive()`. A `Reply` socket binds, receives messages through an async iterator, converts the message to a number, doubles it, and sends the result. The examples show message passing and request-response semantics within Node.js processes, while leaving application decisions such as authentication, retries, persistence, and timeouts outside the library.

Installing zeromq.js and Running Push/Pull

The README installation path uses prebuilt binaries and npm. Install the package with the following command. The documented runtime requirement is Node.js v12 or later with N-API support.

npm install zeromq

Create a producer with the documented `Push` socket example. It binds to the endpoint and sends a message every 500 milliseconds.

import * as zmq from "zeromq"

async function run() {
  const sock = new zmq.Push()
  await sock.bind("tcp://127.0.0.1:3000")
  console.log("Producer bound to port 3000")
  while (true) {
    await sock.send("some work")
    await new Promise(resolve => {
      setTimeout(resolve, 500)
    })
  }
}
run()

The corresponding worker connects and consumes messages through an async iterator.

import * as zmq from "zeromq"

async function run() {
  const sock = new zmq.Pull()
  sock.connect("tcp://127.0.0.1:3000")
  console.log("Worker connected to port 3000")
  for await (const [msg] of sock) {
    console.log("work: %s", msg.toString())
  }
}
run()

Run the producer and worker as separate Node.js processes. The producer should print its bound-port message, while the worker should print the received work at the producer's send interval. The repository also contains `examples/push-pull/` and examples for `majordomo`, `pub-sub`, `queue`, `req-rep`, `threaded-worker`, and `v5-compat`.

Pub/Sub and Req/Rep Examples

The Pub/Sub example uses separate `Publisher` and `Subscriber` processes. The publisher binds to `tcp://127.0.0.1:3000` and sends a multipart envelope. The subscriber connects to the endpoint and subscribes to the topic `"kitty cats"`. Received values are separated into `topic` and `msg`, allowing the application to inspect the topic and payload independently.

This differs from Push/Pull. Push/Pull sends work through a socket pair without the subscription filter shown in the Pub/Sub example. Pub/Sub is organized around publishers, subscribers, and topic selection. The README does not document persistence, replay, delivery guarantees, or automatic missed-message handling for these examples. An application should not infer those properties from the sample code.

The Req/Rep example has a different explicit pairing rule. The client creates a `Request` socket, connects, sends `"4"`, and awaits `receive`. The server creates a `Reply` socket, binds, iterates over incoming messages, and sends the doubled value. A deployment mistake can prevent a useful first test: both processes must use matching socket types and the endpoint must be reachable between client and server.

The async iterator support keeps consumer code inside an async function, but the README examples do not document socket shutdown, cancellation, retry, or backoff behavior. Those concerns belong in the application. The repository's `examples/req-rep/` directory provides the project-specific reference for the complete pattern, while the README shows the core socket calls.

Migration Through zeromq/v5-compat

Applications upgrading from earlier ZeroMQ.js versions can use the `zeromq/v5-compat` compatibility layer. The README describes it as compatibility for ZeroMQ.js versions 4 and 5 and recommends it for upgrades. Its API uses `zmq.socket("pub")` and `zmq.socket("sub")` rather than the newer socket classes.

The documented pattern binds and connects endpoints and then uses the `pub.send` and `sub.on("message")` interfaces. This is useful when an existing codebase already depends on callback-style socket creation or event handlers. It also creates two API styles inside the package, so maintainers need to decide whether new code should use the class-based interface or retain compatibility imports.

The package contains `v5-compat.js` and `v5-compat.d.ts`. Its TypeScript section documents typings for TypeScript 3.0.x and later. For TypeScript below 3.6, the README says to set `compilerOptions.target` to `esnext` or later, such as `es2018`, or add `es2015` and `ESNext.AsyncIterable` to `compilerOptions.lib`, including corresponding polyfills if needed.

That compatibility is a migration aid, not a complete behavioral specification. The README does not provide a full list of differences between the current API and `zeromq/v5-compat`. Existing deployments should inspect the compatibility declarations and test endpoint behavior, message handling, security options, and shutdown paths before replacing current imports.

Native Dependencies, Optional Features, and Limits

zeromq.js is not a pure JavaScript implementation. `package.json` sets `gypfile` to `true`, and the repository includes `CMakeLists.txt`, `docker/`, `vcpkg.json`, native source directories under `src/`, and generated output under `lib/`. The README presents prebuilt binaries as the normal installation route. That can simplify setup when a matching binary is available, but it leaves platform and build considerations that a pure npm package would not have.

The README names additional build paths, including system `libzmq`, Curve with Libsodium, Draft support, Websocket support, secure Websocket support, a `Not Synchronous Resolve` option, and a macOS deployment target. The README does not include detailed commands for every option, so no additional commands or defaults are asserted here.

The project is suitable when the application wants explicit socket-level semantics and can manage native dependencies. It is the wrong tool when the requirement is a hosted queue, a managed relay, automatic service discovery, or a complete RPC framework. Those responsibilities are not described as the purpose of this package. The examples also show continuous loops without documented cancellation or retry logic, so production behavior around shutdown and failure must be handled by the application.

The repository is not archived. The last push was on 2026-10-01. Listed releases include v6.8.0 on 2026-09-09, v6.7.0 on 2026-09-04, and v6.6.0 on 2026-08-12. The README does not establish a support policy for every native platform.

Native ØMQ Compared with zeromq.js

The relevant alternative is using the native ØMQ library directly. The README describes zeromq.js as semantically similar to native ØMQ, but Node.js developers need bindings to interact with that library from a Node.js process. Direct native development gives control over the ØMQ API and its native build configuration, while zeromq.js adds JavaScript socket classes, async functions, async iterators, and TypeScript declarations.

The practical difference is the programming surface. Native ØMQ examples follow the conventions of the native project. zeromq.js examples use `import` or `require`, promises such as `await sock.send`, and `for await` loops over socket messages. The package also exposes the older socket and callback model through `zeromq/v5-compat`, reducing the migration gap for existing code.

The trade-off is dependency and deployment control. The native route requires developers to manage the native library and platform integration themselves. zeromq.js packages that integration for Node.js and offers prebuilt binaries, but the repository still contains native build inputs and optional feature switches. Neither approach automatically supplies broker features such as durable queues or centralized administration.

For teams already standardized on Node.js and TypeScript, zeromq.js is the more direct route. For projects already built around native ØMQ, changing process boundaries solely to use zeromq.js would add migration work without a documented requirement.

Editorial conclusion

Adopt zeromq.js when the application needs explicit ØMQ socket patterns, JavaScript async control, and direct access to native-backed messaging. Do not choose it as a replacement for a broker, managed queue, or complete RPC framework when those services are required. Verify first that the target Node.js version, platform, libzmq build, optional Curve or WebSocket support, and deployment constraints match the package configuration.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. zeromq/zeromq.js on GitHub