Core Subscriptions

Support for GraphQL Subscriptions in gqless.

Installation#

First, install @gqless/subscriptions into your project's dependencies:

pnpm
npm
yarn

npm install @gqless/subscriptions

Usage#

If you activated subscriptions in the CLI Configuration you should have something like this in your generated client file:

const subscriptionsClient =
  typeof window !== 'undefined'
    ? createSubscriptionsClient({
        wsEndpoint: () => {
          // Modify if needed
          const url = new URL('${endpoint}', window.location.href);
          url.protocol = url.protocol.replace('http', 'ws');
          return url.href;
        },
      })
    : undefined;

//...

export const client = createClient<
  GeneratedSchema,
  SchemaObjectTypesNames,
  SchemaObjectTypes
>({
  // ...
  subscriptionsClient,
});

It basically enables subscriptions only on client side, in case you are using SSR.

It's important to note that wsEndpoint can be a string, a function that returns a string or and an async function that returns a string.

setConnectionParams#

subscriptionsClient returns a helper in where you can set the connection parameters for the websocket connection, normally used for authorization purposes.

The second parameter is an optional boolean flag that automatically will reset the websocket connection if it's already connected.

const subscriptionsClient =
  typeof window !== 'undefined'
    ? createSubscriptionsClient({
        wsEndpoint: () => {
          // Modify if needed
          const url = new URL('${endpoint}', window.location.href);
          url.protocol = url.protocol.replace('http', 'ws');
          return url.href;
        },
      })
    : undefined;

const { setConnectionParams } = subscriptionsClient || {};

export { setConnectionParams };

// ...

import { setConnectionParams } from '../gqless';

// ...

let resetWebsocketConnection = true;

setConnectionParams(
  {
    token: 'zLjYkmrdX5...',
  },
  resetWebsocketConnection
);

Lazy behavior#

By default the subscriptions client uses a lazy behavior, which means that it will create the connection only when you actually make a subscription, and disconnect after a couple seconds on last unsubscribe.

createSubscriptionsClient({
  //...

  /**
   * Controls when should the connection be established.
   *
   * `false`: Establish a connection immediately.
   *
   * `true`: Establish a connection on first subscribe and close on last unsubscribe.
   *
   * @default true
   */
  lazy: false,
});

More options#

Name	Type	Default Value	Description
reconnect	`boolean`	`true`	Should the websocket connection try to reconnect
maxReconnectAttempts	`boolean`	`Infinity`	Amount of reconnection attempts
connectionCallback	`() => void`	`undefined`	Callback after successful connection
failedConnectionCallback	`(payload: unknown) => Promise<void>`	`undefined`	Callback after failed connection
failedReconnectCallback	`() => void`	`undefined`	Callback after last reconnection attempt failed
connectionInitPayload	`(() => Promise<Record<string, unknown>>` or `Record<string, unknown>`	`{}`	Connection init payload, or async function to get the init payload before connection, overridable with setConnectionParams
headers	`Record<string,string>`	`undefined`	Might not be actually supported by browsers, use connection params. Headers to be set on websocket connection
lazy	`boolean`	`true`	See Lazy behavior