Quickstart guide using BigState Client Vue

BigState Client Vue is a lightweight wrapper around the core BigState JavaScript SDK. It provides a composable-based interface for subscribing to BigState real-time deliveries inside Vue 3 applications.

The API closely matches the React version, but follows the Vue Composition API conventions: instead of React hooks, BigState Vue exposes a composable named useBigState.

Requirements#

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

• Vue 3.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.vue

Basic usage#

useBigState — Vue composable 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), and returns the reactive state map (bigState) for all provided SIDs inside your Vue component.

<script setup lang="ts">
import { useBigState } from "bigstate.client.vue";

const DELIVERY = "deliveryWs";
const SID = "simple:counter";

const { bigState, lastChanged, retry } = useBigState(
  [DELIVERY],
  [SID],
  optionsHttp,
  optionsWs,
);
</script>

• 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#

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#

<script setup lang="ts">
import { useBigState } from "bigstate.client.vue";

const DELIVERY = "delivery";
const SID = "simple:counter";

const { bigState } = useBigState(
  [DELIVERY],
  [SID],
  {
    baseUrl: import.meta.env.VITE_BS_BASE_URL,
    apiKey: import.meta.env.VITE_BS_API_KEY,
  },
  {
    baseUrl: import.meta.env.VITE_BS_WS_BASE_URL,
    apiKey: import.meta.env.VITE_BS_API_KEY,
  }
);
</script>

<template>
  <div class="counter-container">
    {{ bigState[SID]?.currState?.value.count }}
  </div>
</template>

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.

<script setup lang="ts">
import { watch } from "vue";
import { useBigState, matchPattern } from "bigstateclient.vue";

const SID = "simple:counter";
const DELIVERY = "delivery";

const { lastChanged } = useBigState(
  [DELIVERY],
  [SID],
  {
    baseUrl: import.meta.env.VITE_BS_BASE_URL,
    apiKey: import.meta.env.VITE_BS_API_KEY,
  },
  {
    baseUrl: import.meta.env.VITE_BS_WS_BASE_URL,
    apiKey: import.meta.env.VITE_BS_API_KEY,
  }
);

watch(
  () => lastChanged.value,
  () => {
    const curr = lastChanged.value?.currState?.value;
    const isMatching = matchPattern(SID, lastChanged.value?.sid ?? "");

    if (!curr || !isMatching) return;

    // handle update
    console.log("New value:", curr);
  }
);
</script>