Subscription Exchange

Handle real-time GraphQL subscriptions using Server-Sent Events or WebSocket.

Basic Usage

Server-Sent Events (Recommended)

Simple HTTP-based protocol recommended for most use cases:

import { createClient, httpExchange, subscriptionExchange } from '@mearie/react'; // or @mearie/vue, @mearie/svelte, @mearie/solid
import { createClient as createSSEClient } from 'graphql-sse';
import { schema } from '$mearie';

export const client = createClient({
  schema,
  exchanges: [
    httpExchange({ url: 'https://api.example.com/graphql' }),
    subscriptionExchange({
      client: createSSEClient({
        url: 'https://api.example.com/graphql',
      }),
    }),
  ],
});

Install graphql-sse

npm install graphql-sse

WebSocket

Alternative protocol with lower latency:

import { createClient, httpExchange, subscriptionExchange } from '@mearie/react'; // or @mearie/vue, @mearie/svelte, @mearie/solid
import { createClient as createWSClient } from 'graphql-ws';
import { schema } from '$mearie';

export const client = createClient({
  schema,
  exchanges: [
    httpExchange({ url: 'https://api.example.com/graphql' }),
    subscriptionExchange({
      client: createWSClient({
        url: 'wss://api.example.com/graphql',
      }),
    }),
  ],
});

Install graphql-ws

npm install graphql-ws

Terminating Exchange

Subscription Exchange is a terminating exchange - it must be one of the last exchanges in your chain, typically placed after httpExchange.

Configuration

Server-Sent Events Options

Configure the SSE client with additional options:

import { createClient as createSSEClient } from 'graphql-sse';
import { schema } from '$mearie';

export const client = createClient({
  schema,
  exchanges: [
    httpExchange({ url: 'https://api.example.com/graphql' }),
    subscriptionExchange({
      client: createSSEClient({
        url: 'https://api.example.com/graphql',
        headers: {
          Authorization: 'Bearer token',
        },
        credentials: 'include',
      }),
    }),
  ],
});

WebSocket Options

Configure the WebSocket client:

import { createClient as createWSClient } from 'graphql-ws';
import { schema } from '$mearie';

export const client = createClient({
  schema,
  exchanges: [
    httpExchange({ url: 'https://api.example.com/graphql' }),
    subscriptionExchange({
      client: createWSClient({
        url: 'wss://api.example.com/graphql',
        connectionParams: {
          authToken: 'your-token',
        },
        retryAttempts: 3,
        shouldRetry: () => true,
      }),
    }),
  ],
});

Exchange Chain Placement

Place subscriptionExchange as a terminating exchange:

import { createClient as createSSEClient } from 'graphql-sse';
import { schema } from '$mearie';

export const client = createClient({
  schema,
  exchanges: [
    dedupExchange(),
    retryExchange(),
    cacheExchange(),
    httpExchange({ url: 'https://api.example.com/graphql' }),
    subscriptionExchange({
      client: createSSEClient({
        url: 'https://api.example.com/graphql',
      }),
    }),
  ],
});

Next Steps

• Subscriptions Guide - Learn how to use subscriptions in your app
• HTTP Exchange - Send queries and mutations over HTTP
• Exchanges - Learn about the exchange system