Registry / devops / graphql-lambda-subscriptions

graphql-lambda-subscriptions

library6.0.0jsnpmunverified

GraphQL subscriptions on AWS Lambda using API Gateway WebSockets and DynamoDB, compatible with the graphql-ws protocol. Version 6.0.0 is stable with no recent changes. It provides a serverless alternative to graphql-ws, eliminating the need for a persistent WebSocket server. Key differentiators: uses only DynamoDB, API Gateway, and Lambda; supports optional step functions for ping/pong; offers lifecycle hooks for subscriptions; and is TypeScript-compatible. Release cadence is irregular, with the last release over a year ago.

devops messaging

npm install graphql-lambda-subscriptions

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-LAMBDA-SUB

graphql-lambda-subscriptions

devopsjavascriptv6.0.0

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.

makeServer

✓ import { makeServer } from 'graphql-lambda-subscriptions'

✗ const makeServer = require('graphql-lambda-subscriptions').makeServer

Package is ESM-only; CommonJS require will not work.

✓ import { subscribe } from 'graphql-lambda-subscriptions'

✗ import { subscribe } from 'graphql-lambda-subscriptions/main'

Use the package entry point; no subpath exports.

PubSub (if exported)

✓ import { PubSub } from 'graphql-lambda-subscriptions'

✗ import PubSub from 'graphql-lambda-subscriptions'

PubSub is a named export, not default.

Creates a GraphQL subscription server on AWS Lambda with DynamoDB persistence and exports the WebSocket handler.

import { makeServer } from 'graphql-lambda-subscriptions'; import { DynamoDB } from 'aws-sdk'; import { makeExecutableSchema } from '@graphql-tools/schema'; const dynamodb = new DynamoDB.DocumentClient({ region: process.env.AWS_REGION ?? 'us-east-1' }); const typeDefs = ` type Query { ping: String } type Subscription { message: String } `; const resolvers = { Query: { ping: () => 'pong' }, Subscription: { message: { subscribe: () => (async function* () { yield { message: 'hello' }; })() } }, }; const schema = makeExecutableSchema({ typeDefs, resolvers }); const subscriptionServer = makeServer({ dynamodb, schema }); export const handler = subscriptionServer.webSocketHandler;

Debug

Known issues

breakingThe package dropped CommonJS support in v6.0.0; only ESM is available.

fix

Use ES module imports (import { makeServer } from 'graphql-lambda-subscriptions') or stay on v5.x.

affects: >=6.0.0

breakingAWS SDK v2 is required; v3 is not yet supported. Peer dependency specifies aws-sdk >=2.0.0.

fix

Install aws-sdk v2 (npm install aws-sdk@2) and use v2 DynamoDB DocumentClient.

affects: >=1.0.0

deprecatedThe 'subscribe' function's signature changed in v5; check documentation for details.

fix

Review the migration guide in the docs folder for v5 changes.

affects: >=5.0.0 <6.0.0

gotchaDynamoDB tables must be pre-created with TTL attribute; the library does not create them automatically.

fix

Create DynamoDB tables named 'Connection' and 'Subscription' (or configured names) with a TTL attribute before deployment.

affects: >=1.0.0

gotchaAPI Gateway WebSocket routes must be configured to point to the Lambda function's webSocketHandler export.

fix

Ensure your API Gateway has $connect, $disconnect, and $default routes all pointing to the same Lambda function that exports the webSocketHandler.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot find module 'graphql-lambda-subscriptions'

Package not installed or CommonJS require used on an ESM-only package.

fix

Run npm install graphql-lambda-subscriptions, and use ES import syntax (import { makeServer } from 'graphql-lambda-subscriptions').

Expected property 'webSocketHandler' on object but got undefined

makeServer() not called or exported incorrectly.

fix

Ensure you call makeServer({ dynamodb, schema }) and export result.webSocketHandler as your Lambda handler.

DynamoDB table 'Connection' does not exist

Required DynamoDB tables are not created.

fix

Create the tables with a primary key 'id' (String) and a TTL attribute. Default table names: 'Connection' and 'Subscription'.

TypeError: Cannot read property 'DocumentClient' of undefined

AWS SDK v2 not installed or import from v3.

fix

Install aws-sdk v2 (npm install aws-sdk@2) and import DynamoDB from 'aws-sdk'.

Upgrade

Version history

6.0.0latest on npm

Audit

Dependencies

aws-sdkrequiredPeer dependency for DynamoDB and API Gateway interactions

graphqlrequiredPeer dependency for GraphQL schema and execution

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubssh://git@github.com/reconbot/graphql-lambda-subscriptions ↗

packagegraphql-lambda-subscriptions ↗

homepagehttps://github.com/reconbot/graphql-lambda-subscriptions ↗