amqplib: the AMQP 0-9-1 client for Node.js, and what v2 changed

What amqplib is for, and who it is aimed at

amqplib is a library for building AMQP 0-9-1 clients in Node.js, and it also ships a ready client for Node.js v18 and later. The package description in package.json calls it "An AMQP 0-9-1 (e.g., RabbitMQ) library and client." Its topics list names amqp, amqp-0-9-1, nodejs, rabbitmq and rabbitmq-client. That is the whole scope.

The audience is Node.js developers who already run an AMQP 0-9-1 broker, almost always RabbitMQ, and who want to publish and consume messages from application code. The library exposes both a high-level API and a low-level API, which the README describes as covering "all bits of the protocol." In practice that means you can call assertQueue and consume without thinking about frames, or drop down and work with the protocol directly when a broker feature has no wrapper.

The boundary matters more than the feature list. The README states plainly that the library does not implement AMQP 1.0 or AMQP 0-10, and links to tracking issues for both. If your broker only speaks AMQP 1.0, this project is not a partial fit. It is no fit at all. The same applies to non-RabbitMQ brokers that deviate from AMQP 0-9-1 extensions, since the library is developed and tested against RabbitMQ.

Two APIs, one protocol: how the callback and promise surfaces differ

The package exposes two entry points, and the choice is made at import time rather than at configuration time. Requiring "amqplib" gives you the promise API, which is declared as the default export in package.json ("main": "./channel_api.js"). Requiring "amqplib/callback_api" gives you the older callback style, exported separately with its own type declarations.

Both surfaces do the same work. In the promise API you await amqplib.connect, then await conn.createChannel, then await ch.assertQueue, and pass a callback to ch.consume. In the callback API the same sequence is nested inside error-first callbacks. The README shows both side by side, and the promise example is roughly the same length because it uses two channels: one for the consumer, one for the sender. The callback example does the same with createChannel called twice inside the connection callback.

A detail worth copying from the examples is the channel split. A channel is not a connection; it is a multiplexed session inside one. Using one channel for publishing and another for consuming is what the README demonstrates, and it keeps a consumer cancellation from disturbing your publisher. The examples also register error listeners on both the connection and each channel, which is not optional in practice: an unhandled channel error can take down the channel silently.

The protocol definitions are generated, not hand-written. The Makefile fetches amqp-rabbitmq-0.9.1.json from the RabbitMQ server repository at tag v3.12.13, runs bin/generate-defs.js to produce lib/defs.js, and minifies it with uglify-js. That build step is why the package has no runtime dependencies at all: the dependency list in package.json is empty. Everything the client needs is either generated into the source tree or provided by Node.js.

Installing amqplib and sending a first message

Installation is a single npm command, and the package requires Node.js 18 or newer according to the engines field.

npm install amqplib

The README's promise example connects to a local broker, asserts a queue, consumes from it, and publishes to it on an interval. A trimmed version that publishes one message and exits looks like this.

const amqplib = require('amqplib');

(async () => {
  const conn = await amqplib.connect('amqp://localhost');
  conn.on('error', (err) => { console.error('Connection error:', err); });

  const ch = await conn.createChannel();
  ch.on('error', (err) => { console.error('Channel error:', err); });

  await ch.assertQueue('tasks');
  ch.sendToQueue('tasks', Buffer.from('something to do'));
})();

After running it, the queue named tasks exists on the broker and holds one message. The Buffer.from call is required: sendToQueue takes a buffer, not a string, and the consumer side reads msg.content.toString() to get the text back.

To run the project's own test suite you need a broker. The package scripts show two ways to get one with Docker.

npm run rabbitmq-4
npm test

The rabbitmq-4 script starts rabbitmq:4.2-alpine with port 5672 published to the host. npm test runs node --test --test-timeout=1000, so each test is capped at one second. A rabbitmq-3 script exists for rabbitmq:3.12-alpine if you need the older broker.

Opt-in recovery and the handler-error event in v2

Version 2.0.0 added automatic recovery, and it is opt-in. The README says that without recovery options, behavior is unchanged, which makes the upgrade path from 1.x mechanical for anyone who does not want the feature.

Recovery is configured through the connect options. You pass initialDelay and maxDelay in milliseconds, a factor, a jitter fraction, and maxRetries. The interesting part is the setup function, which the README says is "Called after every successful (re)connect." That is where you recreate topology and consumers, because the broker does not remember them for you.

const connection = await amqplib.connect('amqp://localhost', {
  recovery: {
    initialDelay: 200,
    maxDelay: 5000,
    factor: 2,
    jitter: 0.2,
    maxRetries: Infinity,
    async setup(model) {
      const ch = await model.createChannel();
      await ch.assertQueue('tasks', {durable: true});
    },
  },
});

The connection then emits connect and disconnect events, which the README's example logs. The callback API accepts the same option object, with setup taking a done callback instead of returning a promise.

The second v2 addition addresses a subtler problem. If a user-supplied event handler throws synchronously, the throw propagates into amqplib internals, and the README warns this "can silently swallow the error, or close the channel or connection." Registering a handler-error listener on the connection and on each channel makes amqplib catch those throws and deliver them to that listener along with the name of the event whose handler threw. The README is explicit that handler-error is not a replacement for error: error is emitted by amqplib for protocol-level failures, handler-error only fires when your own listener throws. If no handler-error listener exists, behavior is unchanged from previous versions.

RabbitMQ 4.1 compatibility and the upgrade cost

The README carries one compatibility warning that should be checked before any upgrade: only version 0.10.7 and later of amqplib is compatible with RabbitMQ 4.1.0 and later. That is an old floor, well below the current 2.0.1, but it matters for anyone pinned to a pre-0.10.7 release by a lockfile they have not revisited.

The release history shows how compressed the recent work is. v1.2.0 landed on 2026-05-09, v2.0.0 on 2026-05-10, and v2.0.1 the same day. A major version bump followed within a day by a patch suggests the recovery and handler-error work was staged and then followed by a quick fix. The last push to the repository was on 2026-05-10, which is more than four months before this writing. The project is not archived, but it is also not receiving current commits, so plan for a quiet dependency rather than a fast-moving one.

The upgrade cost from 1.x to 2.x is low by design. Recovery is opt-in, handler-error only activates when you register a listener, and the package has no runtime dependencies to reconcile. The larger maintenance cost is not the library at all: it is the broker version matrix. The Makefile pins RABBITMQ_SRC_VERSION to v3.12.13 for code generation, while the test scripts offer 3.12-alpine and 4.2-alpine containers. If you run a broker version outside that range, the test suite is not evidence that your setup works.

On licensing, the package.json declares "license": "MIT", and the repository root contains both LICENSE and LICENSE-MIT files. The repository metadata reports the license as NOASSERTION, which is a detection artifact rather than a different grant. Read both files before relying on either label; this is a description of what the files say, not legal advice.

When amqplib is the wrong tool

The clearest failure mode is protocol mismatch. AMQP 1.0 is a different protocol with a different wire format, and the README states the library does not implement it. A broker that speaks only AMQP 1.0 will reject the connection at the handshake, and no amount of configuration on the client side fixes that. AMQP 0-10 is in the same position.

The second limitation is recovery scope. The setup callback runs after every reconnect, and it is your job to rebuild exchanges, queues, bindings and consumers inside it. The library reconnects the socket; it does not replay your topology from a stored description. If your setup function is incomplete, you get a connection that looks healthy and a consumer that receives nothing. That is a silent failure, and it is the kind of thing that only shows up under a broker restart.

The third is that this is a RabbitMQ-shaped client. The protocol definitions are generated from RabbitMQ's own codegen JSON, and the examples directory is built around RabbitMQ tutorials. Brokers that implement AMQP 0-9-1 with different extension support may work for basic publish and consume and fail on the parts you actually need.

Finally, there is the maintenance question. With the last push on 2026-05-10 and no commits since, the project is stable rather than active. That is fine for a protocol library whose target protocol has not changed. It is less fine if you are waiting on a fix for a broker version released after that date.

Alternatives and how their approach differs

The most common comparison is against the RabbitMQ team's own Node.js client, which is a separate package with a different design centre. The practical difference is scope: amqplib is an AMQP 0-9-1 library that happens to work well with RabbitMQ, while a vendor client is built around that vendor's features first. If you depend on broker-specific behaviour, the vendor client is the more natural home for it.

On the protocol axis, the real alternative is an AMQP 1.0 client. That is not a drop-in replacement, because AMQP 1.0 has a different model of links and sessions, and the README's own issue tracker treats 1.0 support as out of scope rather than pending. Choosing between them is a broker decision, not a library decision.

Within Node.js, the other option is to skip the client library and talk to a broker over a different transport entirely, for example an HTTP-based API. That trades the persistent connection and push-based delivery of AMQP for request and response semantics, which is a much worse fit for work queues and a reasonable fit for occasional publishes.

For TypeScript users, amqplib ships its own declarations: index.d.ts for the promise API and callback_api.d.ts for the callback API, wired through the exports map in package.json. That means you do not need a separate @types package, and the types track the version you installed.

Editorial conclusion

Adopt amqplib when your broker speaks AMQP 0-9-1 and your runtime is Node.js 18 or newer. Do not adopt it for AMQP 1.0 or AMQP 0-10, which the README states the library does not implement. Before writing code, confirm your RabbitMQ version against the compatibility note, and decide whether you want the recovery option or your own reconnect loop.

Frequently asked questions

Official sources

1. amqp-node/amqplib on GitHub
2. Issues
3. Project website
4. README
5. Releases