GraphQL Over Shared WebSocket for Apollo Client

It indexes GraphQL subscriptions by payload to avoid duplicate subscription channels across browsing contexts.

It is built on top of graphql-shared-ws, a drop-in wrapper around graphql-ws, and uses a SharedWorker to coordinate a single underlying WebSocket connection across browser tabs, windows, and iframes.

💡 Why use it?

• Reuse a single WebSocket connection across tabs, windows, and iframes
• Reduce duplicate subscription traffic and unnecessary connection overhead
• Keep shared GraphQL subscriptions consistent across browsing contexts
• Works as a direct replacement for standard graphql-ws usage in Apollo

💡 If you are using TanStack Query (React Query) or graphql-ws, refer to the official graphql-shared-ws documentation.

📦 Installation

npm install apollo-shared-ws
Copy

pnpm add apollo-shared-ws
Copy

pnpm add apollo-shared-ws --filter="./packages/my-workspace"
Copy

pnpm add apollo-shared-ws -w
Copy

yarn add apollo-shared-ws
Copy

yarn workspace <workspace-name> add apollo-shared-ws
Copy

yarn add -W apollo-shared-ws
Copy

💻 Quick start

import { GraphQLWsLink } from '@apollo/client/link/subscriptions'
import { ApolloClient, ApolloLink, InMemoryCache } from '@apollo/client'
import { setupRestartSubscription } from 'apollo-shared-ws'
import { createSharedClient } from 'graphql-shared-ws'
import { authLink } from './util/authLink'

const wsLink = new GraphQLWsLink(
  // use 'createSharedClient'.
  createSharedClient({
    url: 'wss://localhost:443/api/graphql',
    connectionParams: {
      headers: {
        authorization: 'auth-token-1234',
      },
    },
  })
)

const apolloClient =
  //  use setupRestartSubscription to enable subscription restarts.
  //    wrap ApolloClient with setupRestartSubscription(...)
  setupRestartSubscription(
    new ApolloClient({
      link: ApolloLink.from([authLink, wsLink]),
      cache: new InMemoryCache(),
    })
  )
Copy

If you are using ApolloLink.split, refer to this documentation.

⚙️ How it works ( Architecture )

It uses SharedWorkers to host a single shared WebSocket connection and indexes subscription payloads to avoid duplicate GraphQL subscription channels across browsing contexts.

🌐 Support for SharedWorkers depends on the browser and may be restricted by privacy settings or unsupported environments.

🔌 API documentation

1. apollo-shared-ws API reference
2. graphql-shared-ws documentation
3. graphql-ws documentation
4. Apollo GraphQLWsLink documentation

🤖 Migration automation

This package includes a lightweight migration helper for Apollo Client projects.

Run the following commands sequentially:

npm i --save-dev ts-morph
npx gql-shr-ws-link-migrate --help
npx gql-shr-ws-link-migrate
Copy

This automation:

• adds webSocketImpl: SharedWebSocket to createClient(...) calls
• wraps ApolloClient instantiations with setupRestartSubscription(...)

This is helpful for simple migration cases, but it has limitations. For example, Subscription.restart is not automatically migrated when ApolloLink.split is used.

👥 Community & Support

• 💬 Have an idea? Suggest new features in GitHub Discussions.

• 🚀 Want to support the project? Visit this link.

• 💼 Need custom work or consultation? I am available for hire! Reach out via email.

📦 Related packages

• graphql-shared-ws
• apollo-state-sync
• graphql-ws