Relay exposes the following APIs to create subscriptions.
const {requestSubscription} = require('react-relay'); type Variables = {[name: string]: any}; requestSubscription( environment: Environment, config: { subscription: GraphQLTaggedNode, variables: Variables, onCompleted?: ?() => void, onError?: ?(error: Error) => void, onNext?: ?(response: ?Object) => void, updater?: ?(store: RecordSourceSelectorProxy) => void, }, );
Now let's take a closer look at the config
:
subscription
: the graphql
tagged subscription query.variables
: an object that contains the variables needed for the subscription.onCompleted
: a callback function executed when the subscription is closed by
the peer without error.onError
: a callback function executed when Relay or the server encounters an
error processing the subscription.onNext
: a callback function executed each time a response is received from
the server, with the raw GraphQL response payload.updater
: an optional function that can supply custom logic for updating the
in-memory Relay store based on the server response.In a simple subscription, you only need subscription
and variables
. This is
appropriate when you are only changing the properties of existing records that
can be identified by their id
:
const { requestSubscription, graphql, } = require('react-relay'); const subscription = graphql` subscription MarkReadNotificationSubscription( $storyID: ID! ) { markReadNotification(storyID: $storyID) { notification { seenState } } } `; const variables = { storyID, }; requestSubscription( yourEnvironment, // see Environment docs { subscription, variables, // optional but recommended: onComplete: () => {/* server closed the subscription */}, onError: error => console.error(error), } );
For more complex use-cases, you may wish to perform custom logic to update
Relay's in-memory cache when each subscription response is received. To do so,
pass an updater
function:
const {ConnectionHandler} = require('relay-runtime'); requestSubscription( environment, { subscription, variables, updater: store => { // Get the notification const rootField = store.getRootField('markReadNotification'); const notification = rootField.getLinkedRecord('notification'); // Add it to a connection const viewer = store.getRoot().getLinkedRecord('viewer'); const notifications = ConnectionHandler.getConnection(viewer, 'notifications'); const edge = ConnectionHandler.createEdge( store, notifications, notification, '<TypeOfNotificationsEdge>', ); ConnectionHandler.insertEdgeAfter(notifications, edge); }, }, );