From 9b6df40354ef7693519713a21e432c5b531da241 Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Mon, 20 Jul 2026 19:31:25 +0200
Subject: [PATCH] feat(preferred): add kafkajs replacement

---
 docs/modules/kafkajs.md  | 60 ++++++++++++++++++++++++++++++++++++++++
 manifests/preferred.json | 16 +++++++++++
 2 files changed, 76 insertions(+)
 create mode 100644 docs/modules/kafkajs.md

diff --git a/docs/modules/kafkajs.md b/docs/modules/kafkajs.md
new file mode 100644
index 00000000..cea9b3b3
--- /dev/null
+++ b/docs/modules/kafkajs.md
@@ -0,0 +1,60 @@
+---
+description: Modern alternatives to the kafkajs package
+---
+
+# Replacements for `kafkajs`
+
+`kafkajs` is [no longer maintained](https://github.com/tulios/kafkajs/issues/1603). Both replacements below are actively maintained [Kafka](https://kafka.apache.org/) clients; choose based on your runtime and migration requirements.
+
+## `@platformatic/kafka`
+
+[`@platformatic/kafka`](https://github.com/platformatic/kafka) is a modern, pure TypeScript/JavaScript Kafka client with no native addon. It uses separate producer, consumer, and admin clients, and provides type-safe APIs, serializers, and stream-based consumers.
+
+Example:
+
+<!-- prettier-ignore -->
+```js
+const { Kafka } = require('kafkajs') // [!code --]
+const { Producer, stringSerializers } = require('@platformatic/kafka') // [!code ++]
+
+const kafka = new Kafka({ // [!code --]
+  clientId: 'my-app', // [!code --]
+  brokers: ['localhost:9092'] // [!code --]
+}) // [!code --]
+const producer = kafka.producer() // [!code --]
+const producer = new Producer({ // [!code ++]
+  clientId: 'my-app', // [!code ++]
+  bootstrapBrokers: ['localhost:9092'], // [!code ++]
+  serializers: stringSerializers // [!code ++]
+}) // [!code ++]
+
+await producer.connect() // [!code --]
+await producer.send({
+  topic: 'events', // [!code --]
+  messages: [{ key: 'event-1', value: 'created' }]
+})
+
+await producer.disconnect() // [!code --]
+await producer.close() // [!code ++]
+```
+
+## `@confluentinc/kafka-javascript`
+
+[`@confluentinc/kafka-javascript`](https://github.com/confluentinc/confluent-kafka-javascript) is Confluent's client, backed by the native `librdkafka` library. Confluent was founded by [Kafka's](https://kafka.apache.org/) creators and is a major contributor to the Kafka project. Its KafkaJS-compatible API can make it a good choice for incremental migrations, but it has native binaries.
+
+Example:
+
+<!-- prettier-ignore -->
+```js
+const { Kafka } = require('kafkajs') // [!code --]
+const { Kafka } = require('@confluentinc/kafka-javascript').KafkaJS // [!code ++]
+
+const kafka = new Kafka({
+  clientId: 'my-app', // [!code --]
+  brokers: ['localhost:9092'] // [!code --]
+  kafkaJS: { // [!code ++]
+    clientId: 'my-app', // [!code ++]
+    brokers: ['localhost:9092'] // [!code ++]
+  } // [!code ++]
+})
+```
diff --git a/manifests/preferred.json b/manifests/preferred.json
index 495dc852..fab7beaf 100644
--- a/manifests/preferred.json
+++ b/manifests/preferred.json
@@ -578,6 +578,12 @@
       "replacements": ["jsx-ast-utils-x"],
       "url": {"type": "e18e", "id": "jsx-ast-utils"}
     },
+    "kafkajs": {
+      "type": "module",
+      "moduleName": "kafkajs",
+      "replacements": ["@platformatic/kafka", "@confluentinc/kafka-javascript"],
+      "url": {"type": "e18e", "id": "kafkajs"}
+    },
     "lodash": {
       "type": "module",
       "moduleName": "lodash",
@@ -2810,6 +2816,11 @@
       "type": "documented",
       "replacementModule": "@11ty/gray-matter"
     },
+    "@confluentinc/kafka-javascript": {
+      "id": "@confluentinc/kafka-javascript",
+      "type": "documented",
+      "replacementModule": "@confluentinc/kafka-javascript"
+    },
     "@eslint-community/eslint-plugin-eslint-comments": {
       "id": "@eslint-community/eslint-plugin-eslint-comments",
       "type": "documented",
@@ -2850,6 +2861,11 @@
       "type": "documented",
       "replacementModule": "@placemarkio/tokml"
     },
+    "@platformatic/kafka": {
+      "id": "@platformatic/kafka",
+      "type": "documented",
+      "replacementModule": "@platformatic/kafka"
+    },
     "@vitest/eslint-plugin": {
       "id": "@vitest/eslint-plugin",
       "type": "documented",