subscriptions-transport-ws

subscriptions-transport-ws was the first WebSocket-based transport implementation for GraphQL subscriptions, created in 2016 by the Apollo/Meteor community and widely adopted across the early GraphQL ecosystem. It defines both a client (SubscriptionClient) and a server (SubscriptionServer) that speak a custom graphql-ws subgraph protocol over a single persistent WebSocket connection, handling subscribe/unsubscribe/data/error/complete message framing and reconnection.

The project has been unmaintained since 2018 and its README now explicitly directs users to migrate to graphql-ws, a separate, actively-maintained implementation of a similar-but-incompatible protocol. It remains listed here for historical/reference purposes and because a large volume of existing production code and documentation still depends on its protocol and API shape.

What You Get

• A SubscriptionClient class for subscribing to GraphQL subscriptions over a single persistent WebSocket
• A SubscriptionServer class for implementing the subscription-transport-ws protocol on the server side
• Automatic reconnection and message queueing while the socket is reconnecting
• Integration hooks historically used by Apollo Client and Apollo Server for subscription support
• A documented message protocol (PROTOCOL.md) covering GQL_CONNECTION_INIT/GQL_START/GQL_DATA/GQL_COMPLETE framing

Common Use Cases

• Maintaining legacy GraphQL applications that were built against this transport before graphql-ws existed
• Understanding the historical GraphQL subscriptions protocol when migrating an older codebase to graphql-ws
• Reference implementation study for teams building a custom WebSocket-based subscription transport
• Interop shims that bridge older subscriptions-transport-ws clients to newer graphql-ws servers during a phased migration

Under The Hood

Architecture The library is split into client.ts (SubscriptionClient, ~680 lines) and server.ts (SubscriptionServer, ~480 lines), which communicate over a small message-type protocol defined in message-types.ts and protocol.ts; the client maintains a single WebSocket connection, multiplexing multiple GraphQL subscriptions over it by tagging each message with an operation id, and includes reconnection/backoff logic built on the backo2 package. Tech Stack Written in TypeScript, compiled via tsc, with runtime dependencies on ws (Node WebSocket implementation), eventemitter3, iterall, symbol-observable, and a peer dependency on graphql itself; the build pipeline additionally produces a browser bundle via Webpack (unpkg-webpack.config.js) for client-side use without a bundler. Code Quality Tests under src/test/ exercise both client and server against a real WebSocket server using mocha, with tslint enforcing style; however, the project has had effectively zero commits since 2018 and its own README states it is unmaintained, so no ongoing code-quality investment should be expected. API Design The client API centers on a SubscriptionClient instance whose request() method returns an Observable-like object matching Apollo Client’s expectations at the time, which made it a near drop-in Apollo Link for early GraphQL subscription support — but this same protocol is incompatible with the newer, simpler graphql-ws protocol, so migration requires updating both client and server, not just swapping the import.