node-rdkafka: the Node client that compiles librdkafka into your install step

npm install triggers node-gyp rebuild, not a plain download

The install path is the first thing to understand. `node-rdkafka` is not a pure JavaScript package. `package.json` sets `"install": "node-gyp rebuild"`, with `configure` and `build` bound to `node-gyp configure` and `node-gyp build`. A `binding.gyp` file and a `src/` directory of C++ sources sit at the repository root, and `librdkafka.js` and `lib/` provide the JavaScript layer.

That means `npm install node-rdkafka` compiles a native addon on the machine that installs it. The stated requirements are Apache Kafka >=0.9, Node.js >=16 (the `engines` field agrees), Linux or Mac, plus OpenSSL. The two runtime dependencies are `bindings` and `nan`, and the dev toolchain is mocha, jshint, node-gyp and jsdoc.

The practical consequence is that a Docker build stage needs a compiler and Python, and a deploy pipeline that runs `npm ci --production` on a locked-down host has to allow the compile step. There is no prebuilt Linux or macOS binary path documented here.

For a first run, installation and use are two lines:

npm install node-rdkafka

const Kafka = require('node-rdkafka');

librdkafka 2.12.0 is pinned, and you can ask the module at runtime

The README states the library currently uses `librdkafka` version `2.12.0`, and `package.json` records the same in a `"librdkafka": "2.12.0"` field. Upgrading the native client is therefore a version bump of this wrapper, not something you configure.

Two utility accessors exist precisely because diagnosing a native client is otherwise guesswork. The `features` property on the root object reports what the compiled client supports, and the documented example output is:

const Kafka = require('node-rdkafka');
console.log(Kafka.features);

// #=> [ 'gzip', 'snappy', 'ssl', 'sasl', 'regex', 'lz4' ]

The companion check is `Kafka.librdkafkaVersion`, documented as printing `2.12.0`. Both belong in your startup log. A container built against a different base image can easily link a different client, and compression or SASL support disappearing at runtime is otherwise a slow mystery.

Configuration is passed straight through to the native library, and the README points at librdkafka's own CONFIGURATION.md for the full list. Not every librdkafka option is supported, and the library throws an error if you pass an invalid value, which at least fails loudly at startup rather than at first publish.

Callbacks named with a _cb suffix, and the five you can register

The binding's extension model is a naming convention: configuration keys ending in `_cb` are callbacks. Some are informational and opt-in, such as `dr_cb`, others return a value, such as `partitioner_cb`.

Five are supported: `partitioner_cb`, `dr_cb` or `dr_msg_cb`, `event_cb`, `rebalance_cb` and `offset_commit_cb`. The last two are the ones that carry the real design decisions. `rebalance_cb` hands partition assignment back to your application at the moment the consumer group rebalances, and `offset_commit_cb` gives you control over when an offset is committed relative to processing.

That control is the reason to pick this client over a pure JavaScript one. Offset commit timing is an important design decision, and the README's Rebalancing and Commits sections document the relevant semantics.

The delivery report callback is the other half. Setting `'dr_cb': true` in the producer configuration enables it, and it tells you per message whether the broker acknowledged it. Without it, produce calls return before delivery, and a silent loss looks like success.

The producer takes a broker list and nothing else is required

A `Producer` needs one configuration key to be constructed, `metadata.broker.list`, with comma separated brokers:

const producer = new Kafka.Producer({
  'metadata.broker.list': 'kafka-host1:9092,kafka-host2:9092'
});

The README then shows a fuller example configuration with several explicit values:

const producer = new Kafka.Producer({
  'client.id': 'kafka',
  'metadata.broker.list': 'localhost:9092',
  'compression.codec': 'gzip',
  'retry.backoff.ms': 200,
  'message.send.max.retries': 10,
  'socket.keepalive.enable': true,
  'queue.buffering.max.messages': 100000,
  'queue.buffering.max.ms': 1000,
  'batch.num.messages': 1000000,
  'dr_cb': true
});

`queue.buffering.max.messages` at 100000 with `queue.buffering.max.ms` at 1000 is a batching policy, and `batch.num.messages` at 1000000 caps a single batch. Those two are throughput decisions with a latency cost: a producer configured this way holds records up to a second before flushing. If your consumers need sub-second visibility, that number is where you look.

The Producer is also usable as a writable stream, so a pipeline can write records without manually managing delivery.

Windows links a prebuilt redistributable, and the README says do not use it in production

The Windows path is genuinely different and worth reading closely.

On Windows the build does not compile librdkafka. It downloads a static binary from NuGet during installation, specifically `librdkafka.redist.2.12.0.nupkg` from `https://globalcdn.nuget.org/packages/`, and links against it. The base URL can be overridden with the environment variable `NODE_RDKAFKA_NUGET_BASE_URL`. You also need node-gyp for Windows, and the repository carries `win_install.ps1` for that setup.

Two consequences follow. The install requires network access to a specific CDN at a pinned version, which matters in an air-gapped or locked-down build. And a version bump changes the download URL, so a mirror has to be updated in step with the package.

On the reliability question the README is unambiguous: it states that it does not recommend using node-rdkafka in production on Windows, that Windows is not tested, and that support may lag Linux and Mac because those are the platforms the library is developed on. Treat Windows as development-only.

Alpine needs musl work, and Kafka 0.9.0.x costs ten seconds per connection

Two operational edges are documented rather than left for you to discover.

The README directs Alpine users to a separate document at `examples/docker-alpine.md`. If your images are Alpine-based, that file is the first thing to read; the standard `node-gyp rebuild` path is not assumed to work.

The second is an old but real Kafka bug, quoted from the librdkafka docs. Due to a bug in Apache Kafka 0.9.0.x, the ApiVersionRequest sent by a client on connect is silently ignored, causing the request to time out after 10 seconds, which stalls every client to broker connection for ten seconds before librdkafka falls back on `broker.version.fallback`. The stated workaround is to set `api.version.request` to `false` on clients talking to 0.9.0.x or older.

If you still run a 0.9.0.x cluster, that ten second stall is per connection and per rebalance, and the fix is a configuration key rather than an upgrade.

Editorial conclusion

node-rdkafka fits a Node.js service that needs Kafka's own semantics, partition balancing, commit control and configurable compression rather than a thin promise wrapper, and it suits Linux and macOS builds where node-gyp and OpenSSL are already present. It does not fit a serverless or immutable deployment without a C++ toolchain, and the README explicitly advises against production use on Windows because that build is untested there. Verify first by installing the package in your target image and printing `Kafka.librdkafkaVersion`, which should read 2.12.0, and then run `make e2e` against a broker on localhost:9092 before writing production producer code.

Frequently asked questions

Official sources

1. Blizzard/node-rdkafka on GitHub
2. Issues
3. License: MIT
4. README
5. Releases