Connect to WebSocket delivery

A delivery is a configured channel that selects objects and routes their state updates to consumers. Deliveries decouple publishers from subscribers: publishers write state over HTTP, while deliveries decide who receives each update.

Open a WebSocket to the delivery host, authenticate, subscribe to a delivery identifier, and receive matching object create, update, and delete events as JSON frames.

Configure the delivery first with Create or update a delivery using channel type 1 (WebSocket). Publish state with Set object state. For a guided SDK path, see Deliver and read state.

Use a restricted subscriber credential

Credentials in browser JavaScript are visible to users.

Configure deliveries in a trusted environment. Give browser sockets only the permission to connect and receive matching updates.

WS
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 BigStateWsDeliveryClient from bigstate.client.javascript.

Install#

  • npm
    npm install bigstate.client.react

useBigState(objects, optionsHttp, optionsWs)#

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#

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#

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#

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.

  • getFileobject
    Optional

    Fetches a binary value referenced by `valueRef` over HTTP.

subscribeLastChanged(listener, pattern?)#

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>;

    }
DeliveryTutorial

© 2024 BigState