Registry / messaging / graphql-kafkajs-subscriptions

graphql-kafkajs-subscriptions

library4.0.10jsnpmunverified

Apollo GraphQL subscriptions over Kafka using kafkajs. Version 4.0.10. Provides a KafkaPubSub class that implements the PubSubEngine interface, allowing GraphQL subscriptions to be backed by Kafka topics. Unlike alternatives like graphql-kafka-subscriptions, this library uses kafkajs (modern Kafka client) and supports per-instance consumer group IDs with prefix or fixed group options. Ships TypeScript types. Requires kafkajs as a peer dependency. Released under MIT license.

messaging

npm install graphql-kafkajs-subscriptions

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-KAFKAJS-SU

graphql-kafkajs-subscriptions

messagingjavascriptv4.0.10

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

KafkaPubSub

✓ import { KafkaPubSub } from 'graphql-kafkajs-subscriptions'

✗ import KafkaPubSub from 'graphql-kafkajs-subscriptions'

Named export, not default. ESM-style import required.

KafkaPubSub

✓ const { KafkaPubSub } = require('graphql-kafkajs-subscriptions')

✗ const KafkaPubSub = require('graphql-kafkajs-subscriptions')

CommonJS requires destructuring the named export.

KafkaMessage

✓ import { KafkaPubSub } from 'graphql-kafkajs-subscriptions'

TypeScript type for subscription payloads. No separate import needed.

Creates a KafkaPubSub instance with Kafka connection and uses it to subscribe and publish GraphQL subscription events.

import { Kafka } from 'kafkajs'; import { KafkaPubSub } from 'graphql-kafkajs-subscriptions'; const kafka = new Kafka({ brokers: [process.env.KAFKA_BROKER ?? 'localhost:9092'], ssl: true, sasl: { mechanism: 'scram-sha-256', username: process.env.KAFKA_USERNAME ?? '', password: process.env.KAFKA_PASSWORD ?? '', }, }); const pubsub = KafkaPubSub.create({ topic: 'my-topic', kafka, groupIdPrefix: 'my-group-prefix', }); // Now use pubsub with Apollo Server const server = new ApolloServer({ typeDefs: gql` type Subscription { message: String } `, resolvers: { Subscription: { message: { subscribe: () => pubsub.asyncIterator(['MESSAGE']), }, }, }, }); // Later, publish pubsub.publish('MESSAGE', { value: 'Hello Kafka!' });

Debug

Known issues

breakingIn v4, consumerConfig.groupId is now the preferred way to set group ID; groupIdPrefix behavior is deprecated because it creates random consumer groups per instance leading to resource leaks in production.

fix

Use consumerConfig.groupId with a fixed group ID for production deployments: KafkaPubSub.create({ consumerConfig: { groupId: 'my-group' } })

affects: >=4.0.0

deprecatedUsing groupIdPrefix alone without consumerConfig.groupId is deprecated in v4 and will generate a warning. It creates a new consumer group for each restart, causing zombies.

fix

Switch to consumerConfig.groupId for a fixed group ID.

affects: >=4.0.0

gotchaWhen using multiple server instances, each instance must have the same topic and a unique consumer group ID (or use groupIdPrefix) to receive all messages.

fix

Ensure each instance has its own consumer group ID when using groupIdPrefix, or share group ID for load balancing.

affects: *

gotchaThe publish() method's second parameter is the payload object, not the Kafka message value directly. The payload will be serialized to JSON and sent as the Kafka message value.

fix

Pass { value: myData } or similar structure to match the expected KafkaMessage interface.

affects: *

gotchaIf you do not provide either groupIdPrefix or consumerConfig.groupId, KafkaPubSub.create() will throw an error.

fix

Always supply one of the two options.

affects: >=4.0.0

breakingPrior to v4, the consumer was created with a static groupId. In v4, groupIdPrefix generates a random suffix; merging the two requires explicit handling.

fix

When upgrading, if you relied on a fixed group ID, pass consumerConfig.groupId explicitly.

affects: <4.0.0

Errors

Common errors & fixes

Error: You must provide either groupIdPrefix or consumerConfig.groupId

Missing required group ID configuration when creating KafkaPubSub.

fix

Add groupIdPrefix or consumerConfig.groupId to the create options: KafkaPubSub.create({ topic: '...', kafka: ..., groupIdPrefix: 'prefix' })

TypeError: pubsub.asyncIterator is not a function

Using a default import instead of named import, or incorrect library version.

fix

Make sure you import { KafkaPubSub } from 'graphql-kafkajs-subscriptions' and not default import.

KafkaJSNumberOfRetriesExceededError: Number of retries exceeded

Kafka broker unreachable or wrong broker configuration.

fix

Check KAFKA_BROKER env var and ensure Kafka is running. Verify SSL/SASL settings.

Error: Topic (my-topic) not found

The specified Kafka topic does not exist on the Kafka cluster.

fix

Create the topic manually or use Kafka auto-creation if enabled.

Upgrade

Version history

4.0.10latest on npm

Audit

Dependencies

kafkajsrequiredRequired peer dependency for Kafka communication, version ^2.2.0

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tomasAlabes/graphql-kafkajs-subscriptions ↗

packagegraphql-kafkajs-subscriptions ↗

homepagehttps://github.com/tomasAlabes/graphql-kafkajs-subscriptions#readme ↗