Registry / messaging / serverless-websocket

serverless-websocket

library1.0.1jsnpmunverified

Low-level library to generate WebSocket URLs for serverless applications using AWS IoT and Cognito identity pools. Current stable version is 1.0.1 (last release). Release cadence is unknown; repository appears inactive with no recent commits. Key differentiators: provides a lightweight, minimal way to obtain a WebSocket URL suitable for MQTT over WebSockets, targeting browser and Node.js. Unlike full-service alternatives like Pusher or Ably, it focuses only on AWS IoT connectivity, leaving the MQTT client choice to the user.

messaging

npm install serverless-websocket

package ↗

INSTALL

IMPORT

SIG · SERVERLESS-WEBSOCK

serverless-websocket

messagingjavascriptv1.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Create

✓ import { Create } from 'serverless-websocket'

✗ const Create = require('serverless-websocket').Create

Package ships TypeScript types, supports ESM.

default (Create)

✓ import Create from 'serverless-websocket'

✗ const Create = require('serverless-websocket')

The package exports only a single function as default export.

Create options

✓ Create({ accountID: '123456789012', identityPoolID: 'us-west-2:...', endpoint: '...', region: 'us-west-2' })

✗ Create({ account_id: '...' })

Parameters are case-sensitive and must match exact property names.

Demonstrates creating a WebSocket URL using AWS IoT and Cognito, with environment variables for configuration.

import Create from 'serverless-websocket'; const websocketURL = await Create({ accountID: process.env.AWS_ACCOUNT_ID ?? '', identityPoolID: process.env.COGNITO_IDENTITY_POOL_ID ?? '', endpoint: process.env.IOT_ENDPOINT ?? '', region: 'us-west-2', }); console.log('WebSocket URL:', websocketURL); // Use with MQTT client // const ws = new WebSocket(websocketURL, ['mqttv3.1']);

Debug

Known issues

gotchaThe package depends on aws-signature-v4 which uses Node.js crypto. In browser environments, you must include a polyfill for crypto.

fix

Install crypto-browserify and set up webpack/browserify shims.

affects: *

gotchaThe library only returns a WebSocket URL; it does not handle MQTT connection or data transfer. Users must implement or use an MQTT client separately.

fix

Use an MQTT-over-WebSocket client like mqtt.js (browser-compatible) to connect to the URL.

affects: *

gotchaThe 'endpoint' parameter is the IoT endpoint from Cognito identity pool configuration, not the AWS IoT endpoint. Using the wrong endpoint will cause connection failures.

fix

Ensure you use the 'iotEndpoint' from the Cognito identity pool's 'Connect to IoT' page, or the endpoint returned by AWS CLI.

affects: *

deprecatedThe package is unmaintained and its dependencies may have security vulnerabilities. Consider using AWS Amplify or aws-mqtt instead.

fix

Migrate to aws-mqtt (https://github.com/kmamykin/aws-mqtt) or AWS Amplify's PubSub module.

affects: *

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'createHmac')

Missing crypto polyfill in browser environment.

fix

Install and configure crypto-browserify as a polyfill for the browser.

Error: Missing required parameter: accountID

The 'accountID' field was not provided or is misspelled.

fix

Provide a valid AWS account ID (12-digit number) as the 'accountID' property.

Error: Invalid identity pool ID format

The identity pool ID must include region prefix (e.g., 'us-west-2:...')

fix

Ensure identityPoolID follows the pattern '<region>:<UUID>'.

TypeError: The 'key' argument must be a Buffer or string

Invalid or missing credentials in the Cognito identity pool.

fix

Verify that the identity pool is configured to allow unauthenticated access or provide proper credentials.

Upgrade

Version history

1.0.1latest on npm

Audit

Dependencies

aws-signature-v4requiredUsed for signing the WebSocket URL request

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

packageserverless-websocket ↗