Skip to content

Latest commit

 

History

History
184 lines (134 loc) · 4.35 KB

README.md

File metadata and controls

184 lines (134 loc) · 4.35 KB

GraphQLReactWS – React GraphQL Subscriptions with graphql-ws and Valtio

NPM Version

A React utility for managing GraphQL subscriptions over WebSockets, with Valtio-powered state and effect hooks.

Table of Contents

Example Usage

Feel free to check out full end-to-end example in examples/next/src/pages/subscription.tsx

Setup

import { GraphQLReactWS } from './GraphQLReactWS';
import { createClient } from 'graphql-ws';

const wsClientOptions = {
  url: 'wss://your-graphql-endpoint/graphql',
  // ...other options
};

const graphql = GraphQLReactWS({ graphqlWsOptions: wsClientOptions });

API

GraphQLReactWS

const graphql = GraphQLReactWS({ graphqlWsOptions });
  • Parameters:
    • graphqlWsOptions: Options for the graphql-ws client.
  • Returns: An object with the following properties:
    • client graphql-ws client
    • subscribe subscribe to a GraphQL subscription
    • useSubscription React hook to subscribe to a GraphQL subscription
    • subscriptionStores Map of subscription stores
    • setSubscriptionData Manually set the data for a subscription store
    • getSubscriptionStore Get a subscription store
    • Effects Register global effects for when data arrives or a subscription completes

useSubscription

A React hook to subscribe to a GraphQL subscription and reactively receive data and errors.

const { data, error, store } = graphql.useSubscription({
  query: MySubscriptionDocument,
  variables: { id: '123' }, // optional if your subscription has no variables
  onData: result => {
    /* handle new data */
  },
  onError: error => {
    /* handle errors */
  },
  enabled: true, // optional, default true
});

  • Parameters:

    • query: The GraphQL subscription document.
    • variables: (optional) Variables for the subscription.
    • onData: (optional) Callback for new data.
    • onError: (optional) Callback for errors.
    • initialData: (optional) Initial data for the store.
    • enabled: (optional) Whether the subscription is active.

  • Returns:

    • data: Latest subscription data.
    • error: Latest error, if any.
    • store: The underlying Valtio store.

setSubscriptionData

Manually set the data for a subscription store.

graphql.setSubscriptionData(
  { query: MySubscriptionDocument, variables: { id: '123' } },
  { data: { ... } }
);
  • Parameters:
    • query: The GraphQL subscription document.
    • variables: (optional) Variables for the subscription.
    • data: The new data to set.

Effects

Register global effects for when data arrives or a subscription completes.

Effects.onData

Register a callback to be called every time the specified operation receives data.

const remove = Effects.onData(MySubscriptionDocument, ({ operation, result, variables }) => {
  // Do something with result.data
});
  • Returns: A function to remove the effect.

Effects.onComplete

Register a callback to be called when the specified operation completes or is stopped.

const remove = Effects.onComplete(MySubscriptionDocument, ({ operation, variables }) => {
  // Do something on completion
});
  • Returns: A function to remove the effect.

Examples

Basic Usage

const { data, error } = useSubscription({
  query: MySubscriptionDocument,
  variables: { id: 'abc' },
  onData: result => {
    console.log('New data:', result.data);
  },
  onError: err => {
    console.error('Subscription error:', err.errors);
  },
});

Global Effects

const removeEffect = Effects.onData(MySubscriptionDocument, ({ result }) => {
  console.log('Received data:', result.data);
});

// Later, to remove the effect:
removeEffect();

Manually Setting Data

graphql.setSubscriptionData(
  { query: MySubscriptionDocument, variables: { id: 'abc' } },
  { data: { myField: 'newValue' } },
);