Skip to main content

Core Subscriptions

Support for GraphQL Subscriptions in gqless.

Installation#

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

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#

NameTypeDefault ValueDescription
reconnectbooleantrueShould the websocket connection try to reconnect
maxReconnectAttemptsbooleanInfinityAmount of reconnection attempts
connectionCallback() => voidundefinedCallback after successful connection
failedConnectionCallback(payload: unknown) => Promise<void>undefinedCallback after failed connection
failedReconnectCallback() => voidundefinedCallback 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
headersRecord<string,string>undefinedMight not be actually supported by browsers, use connection params. Headers to be set on websocket connection
lazybooleantrueSee Lazy behavior
Last updated on by Sam Denty