WebSocket API

intermediate

API Gateway WebSocket API with Lambda handlers for $connect, $disconnect, and custom message routes. DynamoDB connections table with userId GSI for server-push messaging.

serverless websocket apigateway lambda dynamodb realtime

Quick Start

Via CLI (recommended)

npx cdk-starter create

Then select "WebSocket API" from the prompt

Or scaffold directly

npx cdk-starter create --starter websocket-api

README

WebSocket API

API Gateway WebSocket API with $connect, $disconnect, and custom message routes backed by Lambda. Active connections stored in DynamoDB with a userId GSI for server-initiated pushes.

Connect

npm install -g wscat
wscat -c wss://<api-id>.execute-api.<region>.amazonaws.com/v1

Send a message

{ "action": "sendmessage", "data": "Hello!" }

Handler files

Route	File
$connect	`src/handlers/connect.ts`
$disconnect	`src/handlers/disconnect.ts`
sendmessage	`src/handlers/message.ts`
$default	`src/handlers/default.ts`

Prerequisites

Node.js ≥ 20
AWS CLI configured (aws configure)
CDK bootstrapped (npx cdk bootstrap)

Deploy

npm install
npx cdk diff
npx cdk deploy

Tear down

npx cdk destroy