{"id":13421,"library":"kinesis-local","title":"AWS Kinesis Local Mock","description":"kinesis-local provides a mock API for AWS Kinesis, enabling developers to simulate Kinesis data streams for local testing and development environments without incurring AWS costs or requiring an internet connection. The current stable version is 0.5.2, with releases occurring periodically to address bug fixes, update dependencies, and improve underlying infrastructure. It is primarily built on Scala, with recent significant updates including an an overhaul from Scala 2 to Scala 3 and an upgrade to Node.js 25 for its Docker image, introduced in v0.5.0. This tool differentiates itself by offering a fully functional local Kinesis endpoint, allowing for comprehensive integration testing of applications that interact with Kinesis, including producers (KPL) and consumers (KCL), directly on a developer's machine.","status":"active","version":"0.5.2","language":"javascript","source_language":"en","source_url":"https://github.com/etspaceman/kinesis-mock","tags":["javascript","kinesis mock","kinesis-mock","kinesis","aws kinesis","aws kinesis mock","aws-kinesis-mock"],"install":[{"cmd":"npm install kinesis-local","lang":"bash","label":"npm"},{"cmd":"yarn add kinesis-local","lang":"bash","label":"yarn"},{"cmd":"pnpm add kinesis-local","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"kinesis-local is a standalone service (an executable server), not a JavaScript library. You interact with it by configuring an AWS SDK Kinesis client to point to its local endpoint (default 4568 for HTTP, 4567 for HTTPS).","wrong":"import Kinesis from 'kinesis-local'; // kinesis-local is an executable service, not a library for direct import.","symbol":"KinesisClient (AWS SDK v3)","correct":"import { KinesisClient, CreateStreamCommand, PutRecordCommand } from '@aws-sdk/client-kinesis';\n\nconst kinesisClient = new KinesisClient({\n  endpoint: 'http://localhost:4568', // Or 'https://localhost:4567'\n  region: 'us-east-1', // Or 'us-west-2' if specified in INITIALIZE_STREAMS\n  credentials: { accessKeyId: 'test', secretAccessKey: 'test' },\n  tls: false // Only if using HTTP endpoint (4568)\n});"},{"note":"For older projects using AWS SDK v2, configure the Kinesis client similarly, ensuring the `endpoint` is set to the mock's address and dummy credentials are provided, as no actual authentication occurs.","symbol":"Kinesis (AWS SDK v2)","correct":"import AWS from 'aws-sdk';\n\nconst kinesis = new AWS.Kinesis({\n  endpoint: 'http://localhost:4568',\n  region: 'us-east-1',\n  accessKeyId: 'test',\n  secretAccessKey: 'test'\n});"},{"note":"While `kinesis-local` bundles a `main.js`, it's intended to be run as a command-line executable via `npx` or Docker. Direct programmatic import of its internal modules is not part of the public API and may be unstable.","wrong":"import { startServer } from 'kinesis-local/main.js'; // Not designed for direct programmatic import and execution as a library; primarily a CLI tool.","symbol":"Running the executable (Child Process)","correct":"import { exec } from 'child_process';\n\n// In a test setup or CI/CD script, you might run kinesis-local as a child process.\nconst kinesisProcess = exec('npx kinesis-local --port 4568');\nkinesisProcess.stdout?.on('data', (data) => console.log(`kinesis-local stdout: ${data}`));\nkinesisProcess.stderr?.on('data', (data) => console.error(`kinesis-local stderr: ${data}`));\n\n// ... later, to stop it\nkinesisProcess.kill();"}],"quickstart":{"code":"import { KinesisClient, CreateStreamCommand, PutRecordCommand } from '@aws-sdk/client-kinesis';\nimport { exec } from 'child_process';\nimport { TextEncoder } from 'util';\n\nconst encoder = new TextEncoder();\nconst streamName = 'my-test-stream';\nconst kinesisLocalPort = 4568; // Default HTTP port\n\nasync function runKinesisLocalDemo() {\n  // 1. Start kinesis-local in a background process\n  console.log('Starting kinesis-local...');\n  const kinesisProcess = exec(`npx kinesis-local --port ${kinesisLocalPort} --initialize-streams ${streamName}:1`);\n\n  kinesisProcess.stdout?.on('data', (data) => console.log(`kinesis-local stdout: ${data}`));\n  kinesisProcess.stderr?.on('data', (data) => console.error(`kinesis-local stderr: ${data}`));\n\n  // Wait a bit for the service to start (in a real app, use a robust health check)\n  await new Promise(resolve => setTimeout(resolve, 5000));\n  console.log('kinesis-local should be running.');\n\n  // 2. Configure AWS SDK Kinesis client to connect to the mock\n  const kinesisClient = new KinesisClient({\n    endpoint: `http://localhost:${kinesisLocalPort}`,\n    region: 'us-east-1', // Match region specified in --initialize-streams or default\n    credentials: { accessKeyId: 'test', secretAccessKey: 'test' }, // Dummy credentials required\n    tls: false // Disable TLS for local HTTP endpoint\n  });\n\n  try {\n    // 3. Put a record into the initialized stream\n    const recordData = encoder.encode(JSON.stringify({ event: 'user_registered', userId: '123' }));\n    console.log(`Putting record to stream: ${streamName}`);\n    const putResult = await kinesisClient.send(new PutRecordCommand({\n      StreamName: streamName,\n      Data: recordData,\n      PartitionKey: 'user-partition-key-1'\n    }));\n    console.log('Record put successfully:', putResult.SequenceNumber);\n\n  } catch (error) {\n    console.error('Error interacting with Kinesis Local:', error);\n  } finally {\n    // 4. Clean up: terminate the kinesis-local process\n    console.log('Stopping kinesis-local...');\n    kinesisProcess.kill();\n    console.log('kinesis-local stopped.');\n  }\n}\n\nrunKinesisLocalDemo();","lang":"typescript","description":"Demonstrates how to install and run the `kinesis-local` mock server using `npx`, then configure an AWS SDK v3 Kinesis client to interact with the locally running mock, including initializing a stream and putting a record into it."},"warnings":[{"fix":"Review your Dockerfiles or local Node.js environment to ensure compatibility with Node.js 25 or newer for the `kinesis-local` executable, if not using `npx` directly which handles the environment.","message":"Version 0.5.0 introduced significant internal overhauls, including an upgrade from Scala 2 to Scala 3 and updating the Docker image to use Node.js 25. While the release notes stated 'no usability changes for users,' ensure your execution environment (especially if running via Docker or `main.js` manually) supports these updated runtimes.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Either stop the conflicting service or configure `kinesis-local` to use different ports (e.g., `npx kinesis-local --port 8000 --tls-port 8001`) and update your AWS SDK client configuration accordingly.","message":"kinesis-local uses default ports 4567 for HTTPS and 4568 for HTTP. If these ports are already in use by other services on your machine, `kinesis-local` will fail to start, leading to connection errors from your application.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your `KinesisClient` or `AWS.Kinesis` constructor includes `credentials: { accessKeyId: 'test', secretAccessKey: 'test' }` for SDK v3 or `accessKeyId: 'test', secretAccessKey: 'test'` for SDK v2.","message":"When configuring AWS SDK clients to connect to `kinesis-local`, you must specify a dummy `accessKeyId` and `secretAccessKey` (e.g., 'test'). The mock service does not perform actual authentication, but the SDK requires these fields to be present to construct requests.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Add `tls: false` to your `KinesisClient` configuration object: `new KinesisClient({ endpoint: 'http://localhost:4568', tls: false, ... })`.","message":"When using `kinesis-local` with AWS SDK v3, if connecting via the HTTP endpoint (default 4568), you should explicitly set `tls: false` in your `KinesisClient` configuration. This prevents the SDK from attempting a secure connection to an insecure endpoint, which would result in TLS/SSL handshake errors.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that `npx kinesis-local` (or your Docker command) is running in a separate terminal without errors. Check for port conflicts, firewall rules, and ensure your AWS SDK client's `endpoint` configuration matches the mock's actual address and port.","cause":"The `kinesis-local` mock server is not running, has crashed, or is not accessible on the specified port, or there's a firewall blocking the connection.","error":"connect ECONNREFUSED 127.0.0.1:4568"},{"fix":"Configure your AWS SDK Kinesis client with dummy credentials: `accessKeyId: 'test', secretAccessKey: 'test'`.","cause":"Your AWS SDK client is attempting to authenticate with AWS Kinesis using either no credentials or incorrect credentials for the local mock. The mock does not perform real authentication but requires dummy credentials to be present.","error":"InvalidAccessKeyId: The security token included in the request is invalid."},{"fix":"Ensure that `StreamName` is correctly provided and is a non-null string in your AWS SDK Kinesis commands. Also, confirm the stream exists, either by creating it programmatically or via the `INITIALIZE_STREAMS` environment variable/CLI option when starting `kinesis-local`.","cause":"An operation was attempted on Kinesis (e.g., `PutRecordCommand`) without specifying a valid `StreamName`.","error":"ValidationException: 1 validation error detected: Value null at 'streamName' failed to satisfy constraint: Member must not be null"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}