Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
KinesisClient (AWS SDK v3)
✓ import { KinesisClient, CreateStreamCommand, PutRecordCommand } from '@aws-sdk/client-kinesis';
const kinesisClient = new KinesisClient({
endpoint: 'http://localhost:4568', // Or 'https://localhost:4567'
region: 'us-east-1', // Or 'us-west-2' if specified in INITIALIZE_STREAMS
credentials: { accessKeyId: 'test', secretAccessKey: 'test' },
tls: false // Only if using HTTP endpoint (4568)
});
✗ import Kinesis from 'kinesis-local'; // kinesis-local is an executable service, not a library for direct import.
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).
Kinesis (AWS SDK v2)
✓ import AWS from 'aws-sdk';
const kinesis = new AWS.Kinesis({
endpoint: 'http://localhost:4568',
region: 'us-east-1',
accessKeyId: 'test',
secretAccessKey: 'test'
});
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.
Running the executable (Child Process)
✓ import { exec } from 'child_process';
// In a test setup or CI/CD script, you might run kinesis-local as a child process.
const kinesisProcess = exec('npx kinesis-local --port 4568');
kinesisProcess.stdout?.on('data', (data) => console.log(`kinesis-local stdout: ${data}`));
kinesisProcess.stderr?.on('data', (data) => console.error(`kinesis-local stderr: ${data}`));
// ... later, to stop it
kinesisProcess.kill();
✗ import { startServer } from 'kinesis-local/main.js'; // Not designed for direct programmatic import and execution as a library; primarily a CLI tool.
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.
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.
import { KinesisClient, CreateStreamCommand, PutRecordCommand } from '@aws-sdk/client-kinesis';
import { exec } from 'child_process';
import { TextEncoder } from 'util';
const encoder = new TextEncoder();
const streamName = 'my-test-stream';
const kinesisLocalPort = 4568; // Default HTTP port
async function runKinesisLocalDemo() {
// 1. Start kinesis-local in a background process
console.log('Starting kinesis-local...');
const kinesisProcess = exec(`npx kinesis-local --port ${kinesisLocalPort} --initialize-streams ${streamName}:1`);
kinesisProcess.stdout?.on('data', (data) => console.log(`kinesis-local stdout: ${data}`));
kinesisProcess.stderr?.on('data', (data) => console.error(`kinesis-local stderr: ${data}`));
// Wait a bit for the service to start (in a real app, use a robust health check)
await new Promise(resolve => setTimeout(resolve, 5000));
console.log('kinesis-local should be running.');
// 2. Configure AWS SDK Kinesis client to connect to the mock
const kinesisClient = new KinesisClient({
endpoint: `http://localhost:${kinesisLocalPort}`,
region: 'us-east-1', // Match region specified in --initialize-streams or default
credentials: { accessKeyId: 'test', secretAccessKey: 'test' }, // Dummy credentials required
tls: false // Disable TLS for local HTTP endpoint
});
try {
// 3. Put a record into the initialized stream
const recordData = encoder.encode(JSON.stringify({ event: 'user_registered', userId: '123' }));
console.log(`Putting record to stream: ${streamName}`);
const putResult = await kinesisClient.send(new PutRecordCommand({
StreamName: streamName,
Data: recordData,
PartitionKey: 'user-partition-key-1'
}));
console.log('Record put successfully:', putResult.SequenceNumber);
} catch (error) {
console.error('Error interacting with Kinesis Local:', error);
} finally {
// 4. Clean up: terminate the kinesis-local process
console.log('Stopping kinesis-local...');
kinesisProcess.kill();
console.log('kinesis-local stopped.');
}
}
runKinesisLocalDemo();
Errors
Common errors & fixes
connect ECONNREFUSED 127.0.0.1:4568
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.
fixVerify 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.
InvalidAccessKeyId: The security token included in the request is invalid.
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.
fixConfigure your AWS SDK Kinesis client with dummy credentials: `accessKeyId: 'test', secretAccessKey: 'test'`.
ValidationException: 1 validation error detected: Value null at 'streamName' failed to satisfy constraint: Member must not be null
An operation was attempted on Kinesis (e.g., `PutRecordCommand`) without specifying a valid `StreamName`.
fixEnsure 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`.
Audit
Dependencies
No dependency data recorded yet.