Run a live dashboard with React

This tutorial uses a ready-made starter: a Node.js publisher writes five BigState object streams, and a React dashboard receives them through one WebSocket delivery.

Node publisher → five object states → WebSocket delivery → React dashboard

The fifth object, image:sequence:player@OWNER, publishes valueRef pointers to PNG frames and demonstrates how to load binary state in the browser with getFile.

Before you begin#

You need Node.js 22.12 or later.

Download the starter#

git clone https://github.com/bigstateio/bigstate-examples.git
cd bigstate-examples/javascript/react/live-dashboard

├── client/       # React dashboard (Black Dashboard UI)
├── publisher/    # Node.js publisher
├── utility/      # Fetches temporary demo credentials on start
└── package.json

Run the app#

From the project root:

npm install
npm run start:all

start:all fetches temporary demo credentials, then starts the publisher and the React client together.

Open the React URL printed in the terminal (usually http://localhost:3000).

You should see:

1. the speed chart filling with new points every second
2. the counter incrementing rapidly
3. the status indicator flipping every five seconds
4. random employee cells highlighted when they change
5. PNG frames cycling in the image panel

How the code works#

The publisher writes five object streams. The React client opens one WebSocket delivery and drives every widget from bigState.

Project roles#

Objects and delivery#

export const DELIVERY = {
  name: 'Dashboard WS delivery',
  objects: Object.keys(OBJECTS),
  type: DeliveryType.WS,
};

Publishing JSON and valueRef#

Most widgets publish JSON:

await client.stateSet(objectName, {
  at: new Date().toISOString(),
  value,
});

The image player uploads frames first, then publishes a valueRef:

await client.stateSetValueRef(
  { object: objectName, filename: 'frame.png', filemimetype: 'image/png' },
  fileBuffer,
);

await client.stateSet(objectName, {
  at: new Date().toISOString(),
  valueRef,
});

withLastState: true reads the previous state before building the next employee list or image frame.

One hook, many objects#

const { bigState, getFile } = useBigState(
  OBJECTS,
  {
    baseUrl: 'https://api.bigstate.dev',
    apiKey: configFile?.rootApiKey ?? '',
  },
  {
    baseUrl: 'https://ws.delivery.bigstate.dev',
    apiKey: configFile?.rootApiKey ?? '',
    deliveries: [DELIVERY_DASHBOARD],
  },
);

Widgets from bigState#

useEffect(() => {
  const speed = bigState?.[OBJECTS[0]]?.currState;
  if (!speed) return;

  setSpeedData(previous =>
    [...previous, { at: speed.at, value: speed.value?.speed ?? null }].slice(-45),
  );
}, [bigState?.[OBJECTS[0]]?.currState]);

Binary frames with getFile#

const getUrl = async valueRef => {
  const blob = await getFile({
    object: OBJECTS[4],
    valueRef,
  });
  if (!blob) return;

  const url = URL.createObjectURL(blob);
  setImageUrl(url);
};

Startup order#

1. utility/fetchOwnerData.js writes temporary credentials.
2. The publisher creates objects and the delivery, then starts per-object timers.
3. The React app calls useBigState once for all objects.
4. Widgets update from delivery-backed bigState, not from publisher return values.

Use your own credentials#

To run against your account instead of demo keys:

1. Create publisher/.env:

BIGSTATE_OWNER=YOUR_OWNER
BIGSTATE_API_KEY=YOUR_SERVER_API_KEY

1. Put matching values in client/src/config.json:

{
  "owner": "YOUR_OWNER",
  "rootApiKey": "YOUR_RESTRICTED_BROWSER_API_KEY"
}

1. Start publisher and client without the demo bootstrap (for example npm run start:server and npm run start:client from the project root), after pointing the publisher at publisher/.env.

If you do not have credentials yet, follow Create an account and save your credentials.

Troubleshooting#

• Confirm you unzipped the full project and ran commands from the project root.
• If npm install fails on peer dependencies, check that client/.npmrc contains legacy-peer-deps=true.
• If the image panel stays empty, check that publisher/src/files/ contains frames and that stateSetValueRef completed without errors.
• A browser 403 usually means the subscriber key needs a broader policy — do not paste a privileged publisher key into the client.

Next steps#