Quickstart guide using BigState Client React

BigState Client React is a lightweight React wrapper around the core BigState JavaScript client. It provides a convenient, declarative hook-based interface for accessing the BigState API directly inside React components.

Requirements#

To use BigState Client React, your project must meet the following requirements:

• Next.js 12.0.0 or higher
• TypeScript (optional) If your project uses TypeScript, version 5.x or higher is recommended.
• bigstate.client.javascript The core JavaScript client is included automatically as a dependency — no manual installation required.

Installation#

npm install bigstate.client.react

Basic usage#

useBigState — React-hook that subscribes to BigState delivery channels over WebSocket and receives real-time updates for the specified subject states (SIDs). It automatically: connects to the WebSocket delivery, fetches initial state values over HTTP, merges and synchronizes the data, tracks the most recent change (lastChanged), returns the current state map (bigState) for all provided sids.

import { useBigState } from 'bigstate.client.javascript';

const { bigState, lastChanged, retry } = useBigState(
  deliveryIds,
  sids,
  optionsHttp,
  optionsWs,
);

• lastChanged is ideal for side effects (notifications, UI updates).
• bigState is the best place to read the current data.
• You can subscribe to multiple deliveryIds and SIDs at the same time.
• Using the generic TMap provides strict type safety for each SID’s value.

Configuration#

Below is a list of the allowed properties.

• deliveryIds - required - array[string] - A list of delivery IDs that updates will be sent through.
• sids - required - array[string] - An array of sids whose states need to be listened to.
• optionsHttp - required - object - An array of sids whose states need to be listened to.
• baseUrl - required - string - this is the root URL to which the client will automatically add the paths of all its HTTP requests. This is the "entry point" to API.
• apiKey - optional - string - the API key used to authenticate requests. It is transmitted to the client if access to service is based on static keys. If an apiKey is specified, the token field is usually not required. How get an ApiKey?
• token - optional - string - the access window that is used to authorize requests. If a token is specified, the apiKey field can be omitted.
• optionsWs - required - object - An array of sids whose states need to be listened to.
• baseUrl - required - string - this is the root URL to which the client will automatically add the paths of all its HTTP requests. This is the "entry point" to API.
• maxReconnectCount - optional - number - Maximum number of reconnection attempts if the WebSocket connection is lost. (11 by default)
• reconnectTime - optional - number - Delay in milliseconds before attempting to reconnect to the WebSocket delivery. (5000 by default)
• apiKey - optional - string - the API key used to authenticate requests. It is transmitted to the client if access to service is based on static keys. If an apiKey is specified, the token field is usually not required. How get an ApiKey?
• token - optional - string - the access window that is used to authorize requests. If a token is specified, the apiKey field can be omitted.

Return values#

The hook returns the object

const result = { bigState, lastChanged, retry };

• bigState - Contains the states of all signed SIDs as an object.
• prevState -object - returns an object containing the previous state value and its timestamp (value, at).
• currState - object - returns an object containing the current state value and its timestamp (value, at).
• error - object - returns an object describing the error, including its value and the time it occurred (value, at).
• lastChanged - Contains information about the latest update.
• sid -string - the unique identifier of the subject.
• currState - object - returns an object containing the current state value and its timestamp (value, at).
• error - object - returns an object describing the error, including its value and the time it occurred (value, at).

Using bigState#

import { useBigState } from 'bigstate.client.javascript';

const SID = "simple:counter";
const DELIVERY = 'deliveryId';

const { bigState } = useBigState(
  [DELIVERY],
  [SID],
  { baseUrl: env.BS_BASE_URL, apiKey: env.BS_API_KEY },
  { baseUrl: env.BS_WS_BASE_URL, apiKey: env.BS_API_KEY },
);

return (
  <div className="counter-container">
    <div>{bigState?.[SID]?.currState?.value.count}</div>
  </div>
);

Reaction to updates (typical case)#

You can also use matchPattern to determine whether the lastChanged event corresponds to the SID you are interested in, especially when subscribing to multiple SIDs.

import { useBigState, matchPattern } from 'bigstate.client.javascript';

const SID = 'simple:counter';
const DELIVERY = 'deliveryId';

const { lastChanged } = useBigState(
  [DELIVERY],
  [SID],
  { baseUrl: env.BS_BASE_URL, apiKey: env.BS_API_KEY },
  { baseUrl: env.BS_WS_BASE_URL, apiKey: env.BS_API_KEY },
);

useEffect(() => {
  const value = lastChanged.value.currState.value;
  const isCurrentSid = matchPattern(SID, lastChanged?.sid ?? '');
  if (!value || !isCurrentSid) return;
  callback(value);
}, [lastChanged]);