sdev-buildz/graphql-shared-ws: GraphQL over WebSocket clients sharing a single socket across browsing contexts. GraphQL subscriptions are indexed by their payloads.

GraphQL over WebSocket clients sharing a single socket across browsing contexts. GraphQL subscriptions are indexed by their payloads. - sdev-buildz/graphql-shared-ws

Summary

GraphQL Shared WS is a TypeScript wrapper for the graphql-ws client that shares a single WebSocket connection across browser tabs, windows, and iframes using a SharedWorker. Subscriptions are indexed by their payloads, so duplicate requests in different UI contexts are merged into one network call. It provides the same API as graphql-ws, making migration simple for existing code.

What it is useful for

When a web application opens the same GraphQL subscription in multiple contexts (for example, a chat widget in the main window and a notification popup in an iframe), each context normally opens its own WebSocket. This library eliminates that duplication by funneling all contexts through one SharedWorker‑hosted connection.

It is useful for:

• Reducing server load and network traffic when the same real‑time data (prices, notifications, live dashboards) is needed in several browsing contexts.
• Keeping subscription state consistent across tabs without manual coordination.
• Projects already using graphql-ws that want the benefits of a shared connection with minimal code changes.

The library relies on the SharedWorker API and the Web Locks API, so it works only in browsers that support these features.

How engineers can use it

1. Install the package, as shown in the README:

   npm install graphql-shared-ws
   

2. Replace the graphql-ws import with the shared client. The README provides this migration snippet:

   // Before
   import { createClient } from 'graphql-ws'
   // After
   import { createSharedClient as createClient } from 'graphql-shared-ws'
   

3. Create a client and start a subscription. The README example:

   import { createSharedClient } from 'graphql-shared-ws'
   
   const sharedClient = createSharedClient({
     url: 'wss://example.com/api/graphql',
   })
   
   sharedClient.subscribe(
     {
       query: `
         subscription listenToMessages {
           messageBroadcasted
         }
       `,
     },
     {
       next: (n) => console.log('Last broadcasted message =', n.data.messageBroadcasted),
       complete: () => console.log('subscription closed.'),
       error: console.error,
     }
   )
   

   The client API (options, subscribe, etc.) is identical to graphql-ws, so existing handlers work unchanged.

Documented limitations and notes

• Browsers block network connections from SharedWorkers when using self‑signed certificates. For local development, launch the browser with --ignore-certificate-warnings (Chrome) or the equivalent flag in your browser.
• The API is the same as graphql-ws except for the webSocketImpl field. If you need a custom WebSocket implementation, refer to the CUSTOM_WEB_SOCKET.md guide mentioned in the README.
• Because it depends on SharedWorker, it is not suitable for environments that disable workers or run in non‑browser contexts.

The README points to the graphql-ws documentation for full API details and to a WORKER_LIFECYCLE.md guide for details on the SharedWorker lifecycle.