{"id":11198,"library":"kafkajs-snappy-typescript","title":"KafkaJS Snappy Codec (TypeScript)","description":"kafkajs-snappy-typescript provides a Snappy compression and decompression codec specifically designed for use with KafkaJS, offering strict TypeScript compatibility. This package serves as a type-safe alternative to `tulios/kafkajs-snappy`, aiming to integrate seamlessly into TypeScript-first KafkaJS applications. It leverages Brooooooklyn's `snappy` Node.js compression library for its core compression logic. The current stable version is 1.0.3, primarily consisting of bug fixes and rebundling efforts to ensure proper NPM publication. As a specialized codec, its release cadence is tied to necessary compatibility updates with KafkaJS or its underlying `snappy` dependency, rather than frequent feature additions. Its key differentiator is its explicit focus on strong typing for KafkaJS environments.","status":"active","version":"1.0.3","language":"javascript","source_language":"en","source_url":"https://github.com/declerckt/kafkajs-snappy-typescript","tags":["javascript","typescript","snappy","kafkajs","codec"],"install":[{"cmd":"npm install kafkajs-snappy-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add kafkajs-snappy-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add kafkajs-snappy-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package registers a custom compression codec with KafkaJS, requiring it to be present in the application environment.","package":"kafkajs","optional":false},{"reason":"Used as the underlying library for the Snappy compression and decompression logic.","package":"snappy","optional":false}],"imports":[{"note":"The primary export is a named class, intended for ESM usage with TypeScript. CommonJS `require` should generally be avoided in favor of ES modules.","wrong":"const { SnappyCodec } = require('kafkajs-snappy-typescript');","symbol":"SnappyCodec","correct":"import { SnappyCodec } from 'kafkajs-snappy-typescript';"},{"note":"While this package provides the codec, KafkaJS's `CompressionTypes` and `CompressionCodecs` are external imports necessary for codec registration.","symbol":"CompressionTypes","correct":"import { CompressionTypes, CompressionCodecs } from 'kafkajs';"}],"quickstart":{"code":"import { Kafka, CompressionTypes, CompressionCodecs } from 'kafkajs';\nimport { SnappyCodec } from 'kafkajs-snappy-typescript';\n\n// Register the Snappy codec with KafkaJS\nCompressionCodecs[CompressionTypes.Snappy] = new SnappyCodec().codec;\n\nconst kafka = new Kafka({\n  clientId: 'my-app',\n  brokers: ['localhost:9092'],\n});\n\nconst producer = kafka.producer();\nconst consumer = kafka.consumer({ groupId: 'test-group' });\n\nasync function run() {\n  await producer.connect();\n  await consumer.connect();\n\n  await producer.send({\n    topic: 'test-topic',\n    compression: CompressionTypes.Snappy, // Use Snappy compression\n    messages: [\n      { value: 'Hello KafkaJS with Snappy!' },\n    ],\n  });\n  console.log('Message sent with Snappy compression.');\n\n  await consumer.subscribe({ topic: 'test-topic', fromBeginning: true });\n\n  await consumer.run({\n    eachMessage: async ({ topic, partition, message }) => {\n      console.log({\n        value: message.value?.toString(),\n        headers: message.headers,\n      });\n    },\n  });\n\n  // Disconnect after a short period for demonstration\n  setTimeout(async () => {\n    await producer.disconnect();\n    await consumer.disconnect();\n    console.log('Producer and consumer disconnected.');\n  }, 5000);\n}\n\nrun().catch(console.error);","lang":"typescript","description":"This quickstart demonstrates how to register the Snappy codec with KafkaJS and then use it to send and receive messages with Snappy compression."},"warnings":[{"fix":"Ensure the codec registration line is executed before any KafkaJS producer or consumer operations that involve Snappy compression.","message":"This package is a codec and must be explicitly registered with KafkaJS via `CompressionCodecs[CompressionTypes.Snappy] = new SnappyCodec().codec;` before producing or consuming Snappy-compressed messages. Failing to register it will result in KafkaJS not knowing how to handle Snappy compression.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Refer to the official `snappy` (Brooooooklyn/snappy) package's installation instructions and ensure all necessary system-level build tools (e.g., Python, C/C++ compiler) are installed and configured for `node-gyp`.","message":"The underlying `snappy` package, used for compression, relies on native C++ bindings. This can sometimes lead to compilation issues during `npm install` on certain environments or architectures if build tools (like `node-gyp` dependencies) are not correctly set up. Check the `snappy` package documentation for specific build requirements.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Choose one Snappy codec library for KafkaJS (either `kafkajs-snappy-typescript` or `kafkajs-snappy`) and stick with it throughout your project for consistency and to avoid potential conflicts.","message":"This library is a TypeScript-focused alternative to `tulios/kafkajs-snappy`. While functionally similar, using both or mixing their import styles could lead to type conflicts or confusion.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `CompressionCodecs[CompressionTypes.Snappy] = new SnappyCodec().codec;` to your application startup code, ensuring it runs before KafkaJS operations.","cause":"The Snappy codec was not registered with KafkaJS's `CompressionCodecs` before a producer attempted to send a Snappy-compressed message or a consumer tried to decompress one.","error":"Error: Unknown compression type"},{"fix":"Ensure you have the necessary build tools installed on your system. For `node-gyp`, this typically includes Python 3, `make` (or Xcode on macOS, Visual C++ Build Tools on Windows). Consult the `node-gyp` and `snappy` documentation for detailed prerequisites.","cause":"The underlying `snappy` package (which uses native code) failed to compile during installation, often due to missing build tools like `python` or `make`, or incorrect compiler setup.","error":"node-pre-gyp ERR! build error"},{"fix":"Ensure you are instantiating the class correctly: `new SnappyCodec().codec`. Also, verify the import path: `import { SnappyCodec } from 'kafkajs-snappy-typescript';`","cause":"You might be attempting to access `.codec` on `SnappyCodec` without instantiating it first, or `SnappyCodec` itself might be undefined due to an incorrect import.","error":"TypeError: Cannot read properties of undefined (reading 'codec')"}],"ecosystem":"npm"}