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.

injectBigState(objects, optionsHttp, optionsWs)

Angular client

From ngx-bigstate-client

Angular helpers that open WebSocket delivery and expose Signals or RxJS streams. Built on BigStateWsDeliveryClient from bigstate.client.javascript.

Install#

npm
```
npm install ngx-bigstate-client
```

injectBigState(objects, optionsHttp, optionsWs)#

RequiredOptional

Subscribe inside an injection context. Closest match to the React and Vue hooks.

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

Signal-based handle returned by injectBigState and createBigStateStream.

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.
lastChangedobject
Optional
Angular `Signal` with the most recent change event, or `null`.
destroyobject
Optional
Tears down the subscription. Prefer this when using `createBigStateStream` outside a component injection context.

Config-based alternative#

App config


import { ApplicationConfig } from '@angular/core';
import { provideBsClientConfig } from 'ngx-bigstate-client';

export const appConfig: ApplicationConfig = {
  providers: [
    provideBsClientConfig({
      http: {
        baseUrl: 'https://api.bigstate.dev',
        apiKey: 'YOUR_RESTRICTED_API_KEY',
      },
      ws: {
        baseUrl: 'https://ws.delivery.bigstate.dev',
        apiKey: 'YOUR_RESTRICTED_API_KEY',
        deliveries: ['deliveryWsQuickstart'],
      },
    }),
  ],
};

Component stream


import { Component, inject } from '@angular/core';
import { NgxBigStateClientService } from 'ngx-bigstate-client';

@Component({
  selector: 'app-counter-live',
  template: `{{ state$ | async | json }}`,
})
export class CounterLiveComponent {
  private readonly bs = inject(NgxBigStateClientService);

  state$ = this.bs.stream(['quickstart:counter@YOUR_OWNER']);
}

Close and reconnect#

Unintentional socket closes reconnect automatically through the underlying JavaScript client. Call retry after delivery errors. Use destroy when you create a stream outside component lifecycle cleanup.

Example#

Subscribe with a restricted browser credential.

injectBigState


import { Component, effect } from '@angular/core';
import { injectBigState } from 'ngx-bigstate-client';

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

@Component({
selector: 'app-counter-live',
template: `<div>Count: {{ count ?? '—' }}</div>`,
})
export class CounterLiveComponent {
private readonly bs = injectBigState(
  [OBJECT_NAME],
  {
    baseUrl: 'https://api.bigstate.dev',
    apiKey: API_KEY,
  },
  {
    baseUrl: 'https://ws.delivery.bigstate.dev',
    apiKey: API_KEY,
    deliveries: [DELIVERY_NAME],
  },
);

count?: number;

constructor() {
  effect(() => {
    const change = this.bs.lastChanged();
    this.count = change?.value.currState?.value?.count;
  });
}
}

Delivery Tutorial

Description
Install
injectBigState(objects, optionsHttp, optionsWs)
optionsHttp
optionsWs
Returns
Config-based alternative
Close and reconnect
Example