{"id":47892,"library":"graphql-lambda-subscriptions","title":"graphql-lambda-subscriptions","description":"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.","status":"active","version":"6.0.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/reconbot/graphql-lambda-subscriptions","tags":["javascript","graphql","lambda","subscriptions","API Gateway","serverless","subscriptionless","AWS","typescript"],"install":[{"cmd":"npm install graphql-lambda-subscriptions","lang":"bash","label":"npm"},{"cmd":"yarn add graphql-lambda-subscriptions","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphql-lambda-subscriptions","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for DynamoDB and API Gateway interactions","package":"aws-sdk","optional":false},{"reason":"Peer dependency for GraphQL schema and execution","package":"graphql","optional":false}],"imports":[{"note":"Package is ESM-only; CommonJS require will not work.","wrong":"const makeServer = require('graphql-lambda-subscriptions').makeServer","symbol":"makeServer","correct":"import { makeServer } from 'graphql-lambda-subscriptions'"},{"note":"Use the package entry point; no subpath exports.","wrong":"import { subscribe } from 'graphql-lambda-subscriptions/main'","symbol":"subscribe","correct":"import { subscribe } from 'graphql-lambda-subscriptions'"},{"note":"PubSub is a named export, not default.","wrong":"import PubSub from 'graphql-lambda-subscriptions'","symbol":"PubSub (if exported)","correct":"import { PubSub } from 'graphql-lambda-subscriptions'"}],"quickstart":{"code":"import { makeServer } from 'graphql-lambda-subscriptions';\nimport { DynamoDB } from 'aws-sdk';\nimport { makeExecutableSchema } from '@graphql-tools/schema';\n\nconst dynamodb = new DynamoDB.DocumentClient({ region: process.env.AWS_REGION ?? 'us-east-1' });\nconst typeDefs = `\n  type Query { ping: String }\n  type Subscription { message: String }\n`;\nconst resolvers = {\n  Query: { ping: () => 'pong' },\n  Subscription: { message: { subscribe: () => (async function* () { yield { message: 'hello' }; })() } },\n};\nconst schema = makeExecutableSchema({ typeDefs, resolvers });\nconst subscriptionServer = makeServer({ dynamodb, schema });\nexport const handler = subscriptionServer.webSocketHandler;","lang":"typescript","description":"Creates a GraphQL subscription server on AWS Lambda with DynamoDB persistence and exports the WebSocket handler."},"warnings":[{"fix":"Use ES module imports (import { makeServer } from 'graphql-lambda-subscriptions') or stay on v5.x.","message":"The package dropped CommonJS support in v6.0.0; only ESM is available.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Install aws-sdk v2 (npm install aws-sdk@2) and use v2 DynamoDB DocumentClient.","message":"AWS SDK v2 is required; v3 is not yet supported. Peer dependency specifies aws-sdk >=2.0.0.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Review the migration guide in the docs folder for v5 changes.","message":"The 'subscribe' function's signature changed in v5; check documentation for details.","severity":"deprecated","affected_versions":">=5.0.0 <6.0.0"},{"fix":"Create DynamoDB tables named 'Connection' and 'Subscription' (or configured names) with a TTL attribute before deployment.","message":"DynamoDB tables must be pre-created with TTL attribute; the library does not create them automatically.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your API Gateway has $connect, $disconnect, and $default routes all pointing to the same Lambda function that exports the webSocketHandler.","message":"API Gateway WebSocket routes must be configured to point to the Lambda function's webSocketHandler export.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'6.0.0':24 'ago':84 'altern':35 'api':11,53,89 'aw':8,93 'cadenc':74 'chang':30 'compat':16,72 'differenti':49 'dynamodb':15,52 'elimin':40 'function':60 'gateway':12,54,90 'graphql':2,5,20,38,86 'graphql-lambda-subscript':1 'graphql-w':19,37 'hook':65 'irregular':76 'javascript':85 'key':48 'lambda':3,9,56,87 'last':79 'lifecycl':64 'need':42 'offer':63 'option':58 'persist':45 'ping/pong':62 'protocol':22 'provid':32 'recent':29 'releas':73,80 'server':47 'serverless':34,91 'stabl':26 'step':59 'subscript':4,6,67,88 'subscriptionless':92 'support':57 'typescript':71,94 'typescript-compat':70 'use':10,50 'version':23 'websocket':13,46 'ws':21,39 'year':83","created_at":"2026-06-07T16:53:52.534195+00:00","updated_at":"2026-06-07T16:53:52.534195+00:00","problems":[{"fix":"Run npm install graphql-lambda-subscriptions, and use ES import syntax (import { makeServer } from 'graphql-lambda-subscriptions').","cause":"Package not installed or CommonJS require used on an ESM-only package.","error":"Cannot find module 'graphql-lambda-subscriptions'"},{"fix":"Ensure you call makeServer({ dynamodb, schema }) and export result.webSocketHandler as your Lambda handler.","cause":"makeServer() not called or exported incorrectly.","error":"Expected property 'webSocketHandler' on object but got undefined"},{"fix":"Create the tables with a primary key 'id' (String) and a TTL attribute. Default table names: 'Connection' and 'Subscription'.","cause":"Required DynamoDB tables are not created.","error":"DynamoDB table 'Connection' does not exist"},{"fix":"Install aws-sdk v2 (npm install aws-sdk@2) and import DynamoDB from 'aws-sdk'.","cause":"AWS SDK v2 not installed or import from v3.","error":"TypeError: Cannot read property 'DocumentClient' of undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/reconbot/graphql-lambda-subscriptions","github":"ssh://git@github.com/reconbot/graphql-lambda-subscriptions","docs":null,"changelog":null,"pypi":null,"npm":"graphql-lambda-subscriptions","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","messaging"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}