Frameworks

React, Angular, and Vue open WebSocket delivery through BigStateWsDeliveryClientExtended and read missing values through the JavaScript client. Pass the same host and credential you would pass when creating those clients. Angular can take that credential in injectBigState, or register it once with provideBsClientConfig and subscribe through NgxBigStateClientService.

useBigState(objects, optionsHttp, optionsWs)

React client

From bigstate.client.react

React hook that opens WebSocket delivery, keeps object state in sync, and fetches missing values over HTTP. Built on BigStateWsDeliveryClientExtended from bigstate.client.javascript.

Install#

npm
```
npm install bigstate.client.react
```

useBigState(objects, optionsHttp, optionsWs)#

RequiredOptional

Subscribe to delivery channels and track the listed objects in React state.

objectsarray[string]
Required
Object names or patterns whose updates should appear in local state.
example:
[ "quickstart:counter@YOUR_OWNER" ]

optionsHttp#

RequiredOptional

HTTP client options used for initial and valueRef reads.

baseUrlstring
Required
HTTP API host used to fetch state when a delivery event has no inline value.
example: https://api.bigstate.dev
apiKeystring
Optional
API key for HTTP reads. Provide either `apiKey` or `token`.
example: YOUR_RESTRICTED_API_KEY
tokenstring
Optional
Session token for HTTP reads. Provide either `apiKey` or `token`.

optionsWs#

RequiredOptional

WebSocket delivery options. deliveries is required in addition to the usual socket fields.

baseUrlstring
Required
Delivery WebSocket host. The client appends `/v1` automatically.
example: https://ws.delivery.bigstate.dev
deliveriesarray[string]
Required
Delivery identifiers to subscribe to over WebSocket.
example:
[ "deliveryWsQuickstart" ]
apiKeystring
Optional
API key for the socket. Provide either `apiKey` or `token`.
example: YOUR_RESTRICTED_API_KEY
tokenstring
Optional
Session token for the socket. Provide either `apiKey` or `token`.
maxReconnectCountnumber
Optional
Maximum reconnect attempts per outage. Default: `500`.
example: 500
reconnectTimenumber
Optional
Base delay in milliseconds for the rapid reconnect phase. Default: `5000`.
example: 5000
reconnectLinearStepMsnumber
Optional
Step in milliseconds for the long reconnect phase. Default: `300000` (5 minutes).
example: 300000
debugboolean
Optional
Enable verbose WebSocket lifecycle logs.
example: true

Returns#

RequiredOptional

Values returned by useBigState.

bigStateobject
Optional
Map of subscribed objects to current and previous state snapshots.
subscribeLastChangedobject
Optional
Registers a listener for the latest change. Call as subscribeLastChanged(listener, pattern?). The first argument is the callback; the optional second argument is an object name or glob pattern that filters which updates invoke the listener. Returns an unsubscribe function.
deliveriesErrorsarray
Optional
Delivery or connection errors collected by the client.
retryobject
Optional
Re-subscribes after failed delivery connections.

subscribeLastChanged(listener, pattern?)#

RequiredOptional

Listen for the latest delivered change. The first argument is the callback; the optional second argument is an object name or glob pattern that limits which updates invoke the listener. Returns an unsubscribe function.

listenerany
Required
Callback invoked when a matching object changes. Receives the latest change event (including currState).
patternstring
Optional
Optional object name or glob pattern. When set, the listener runs only for matching objects. Omit it to receive every change from the subscribed set.
Values
- Exact name — `quickstart:counter@YOUR_OWNER`
- Glob — `quickstart:*@YOUR_OWNER`
example: quickstart:counter@YOUR_OWNER

Close and reconnect#

The hook cleans up handlers when the component unmounts. Unintentional socket closes reconnect automatically through the underlying JavaScript client. Call retry after delivery errors.

Example#

Subscribe with a restricted browser credential. Pass a pattern as the second argument when you only care about one object.

useBigState


import { useEffect } from 'react';
import { useBigState } from 'bigstate.client.react';

const API_KEY = 'YOUR_RESTRICTED_API_KEY';
const OWNER = 'YOUR_OWNER';
const OBJECT_NAME = `quickstart:counter@${OWNER}`;
const DELIVERY_NAME = 'deliveryWsQuickstart';

export function CounterLive() {
	const { subscribeLastChanged, bigState } = useBigState(
		[OBJECT_NAME],
		{
			baseUrl: 'https://api.bigstate.dev',
			apiKey: API_KEY,
		},
		{
			baseUrl: 'https://ws.delivery.bigstate.dev',
			apiKey: API_KEY,
			deliveries: [DELIVERY_NAME],
		},
	);

	useEffect(() => {
		// listener, then optional object pattern
		return subscribeLastChanged(({ value }) => {
			console.log('Latest state:', value.currState?.value);
		}, OBJECT_NAME);
	}, [subscribeLastChanged]);

	const count = bigState[OBJECT_NAME]?.currState?.value?.count;

	return <div>Count: {count ?? '—'}</div>;
}

WebSocket Tutorial

Install
useBigState(objects, optionsHttp, optionsWs)
optionsHttp
optionsWs
Returns
subscribeLastChanged(listener, pattern?)
Close and reconnect
Example