Skip to content

Commit 3bd3969

Browse files
Update README.md (#23)
* Update README.md Updating the Readme to contain more direct messaging about our Early Access. * Update README.md Added suggestions
1 parent d7421ac commit 3bd3969

File tree

1 file changed

+59
-23
lines changed

1 file changed

+59
-23
lines changed

README.md

Lines changed: 59 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,26 @@
11
Confluent's Javascript Client for Apache Kafka<sup>TM</sup>
22
=====================================================
33

4-
**confluent-kafka-js** is Confluent's Javascript client for [Apache Kafka](http://kafka.apache.org/) and the
5-
[Confluent Platform](https://www.confluent.io/product/compare/).
4+
**confluent-kafka-js** is Confluent's JavaScript client for [Apache Kafka](http://kafka.apache.org/) and the
5+
[Confluent Platform](https://www.confluent.io/product/compare/). This is an **early access** library. The goal is to provide an highly performant, reliable and easy to use JavaScript client that is based on [node-rdkafka](https://github.com/Blizzard/node-rdkafka) yet also API compatible with [KafkaJS](https://github.com/tulios/kafkajs) to provide flexibility to users and streamline migrations from other clients.
66

7+
This library leverages the work and concepts from two popular Apache Kafka JavaScript clients: [node-rdkafka](https://github.com/Blizzard/node-rdkafka) and [KafkaJS](https://github.com/tulios/kafkajs). The core is heavily based on the node-rdkafka library, which uses our own [librdkafka](https://github.com/confluentinc/librdkafka/tree/v2.3.0) library for core client functionality. However, we leverage a promisified API and a more idiomatic interface, similar to the one in KafkaJS, making it easy for developers to migrate and adopt this client depending on the patterns and interface they prefer.
8+
__This library currently uses `librdkafka` based off of the master branch.__
79

8-
Features:
9-
10-
- **High performance** - confluent-kafka-js is a lightweight wrapper around
11-
[librdkafka](https://github.com/confluentinc/librdkafka), a finely tuned C
12-
client.
13-
14-
- **Reliability** - There are a lot of details to get right when writing an Apache Kafka
15-
client. We get them right in one place (librdkafka) and leverage this work
16-
across all of our clients (also [confluent-kafka-python](https://github.com/confluentinc/confluent-kafka-python),
17-
[confluent-kafka-go](https://github.com/confluentinc/confluent-kafka-go) and
18-
and [confluent-kafka-dotnet](https://github.com/confluentinc/confluent-kafka-dotnet)).
10+
## This library is currently in early access and not meant for production use
1911

20-
- **Future proof** - Confluent, founded by the
21-
creators of Kafka, is building a [streaming platform](https://www.confluent.io/product/compare/)
22-
with Apache Kafka at its core. It's high priority for us that client features keep
23-
pace with core Apache Kafka and components of the [Confluent Platform](https://www.confluent.io/product/compare/).
12+
**This library is in active development, pre-1.0.0, and it is likely to have many breaking changes.**
2413

25-
## This library is currently not ready for production use. It's an early-access preview in active development, pre-1.0.0, and there might be breaking changes.
14+
For this early-access release, we aim to get feedback from JavaScript developers within the Apache Kafka community to help meet your needs. Some areas of feedback we are looking for include:
15+
- Usability of the API compared to other clients
16+
- Migration experience from the node-rdkafka and KafkaJs
17+
- Overall quality and reliability
2618

27-
This library is based heavily on [node-rdkafka](https://github.com/Blizzard/node-rdkafka).
19+
We invite you to raise issues to highlight any feedback you may have.
2820

29-
This library contains a promisified API, very similar to the one in [kafkajs](https://github.com/tulios/kafkajs). Some of the tests are also based on the ones in kafkajs.
21+
Within the early-access, only **basic produce and consume functionality** as well as the ability to **create and delete topics** are supported. All other admin client functionality is coming in future releases. See [INTRODUCTION.md](INTRODUCTION.md) for more details on what is supported.
3022

31-
__This library currently uses `librdkafka` based off of the master branch.__
23+
To use **Schema Registry**, use the existing [kafkajs/confluent-schema-registry](https://github.com/kafkajs/confluent-schema-registry) library that is compatible with this library. For a simple schema registry example, see [sr.js](https://github.com/confluentinc/confluent-kafka-js/blob/dev_early_access_development_branch/examples/kafkajs/sr.js).
3224

3325

3426
## Requirements
@@ -39,8 +31,7 @@ The following configurations are supported for this early access preview:
3931
* Linux (x64 and arm64) - both glibc and musl/alpine.
4032
* macOS - arm64/m1.
4133

42-
Installation on any of these platforms is meant to be seamless, without any C/C++ compilation required. It can be installed
43-
from GitHub:
34+
Installation on any of these platforms is meant to be seamless, without any C/C++ compilation required. It can be installed from GitHub:
4435

4536
```bash
4637
$ npm install "git+ssh://[email protected]/confluentinc/confluent-kafka-js.git#v0.1.6-devel"
@@ -50,6 +41,51 @@ Yarn and pnpm support is experimental.
5041

5142
# Getting Started
5243

44+
Below is a simple produce example for users migrating from KafkaJS.
45+
46+
```javascript
47+
// require('kafkajs') is replaced with require('confluent-kafka-js').KafkaJS.
48+
const { Kafka } = require("confluent-kafka-js").KafkaJS;
49+
50+
async function producerStart() {
51+
const kafka = new Kafka({
52+
kafkaJS: {
53+
brokers: ['<fill>'],
54+
ssl: true,
55+
sasl: {
56+
mechanism: 'plain',
57+
username: '<fill>',
58+
password: '<fill>',
59+
},
60+
}
61+
});
62+
63+
const producer = kafka.producer();
64+
65+
await producer.connect();
66+
67+
console.log("Connected successfully");
68+
69+
const res = []
70+
for (let i = 0; i < 50; i++) {
71+
res.push(producer.send({
72+
topic: 'test-topic',
73+
messages: [
74+
{ value: 'v222', partition: 0 },
75+
{ value: 'v11', partition: 0, key: 'x' },
76+
]
77+
}));
78+
}
79+
await Promise.all(res);
80+
81+
await producer.disconnect();
82+
83+
console.log("Disconnected successfully");
84+
}
85+
86+
producerStart();
87+
```
88+
5389
1. If you're migrating from `kafkajs`, you can use the [migration guide](MIGRATION.md#kafkajs).
5490
2. If you're migrating from `node-rdkafka`, you can use the [migration guide](MIGRATION.md#node-rdkafka).
5591
3. If you're starting afresh, you can use the [quickstart guide](QUICKSTART.md).

0 commit comments

Comments
 (0)