Realtime and topics

When one person books the last mat, everyone else should see "Full" straight away, without reloading. Every insert, update and delete in your app emits a change event, and one line in a screen follows them. For messages that aren't row changes, publish to a topic.

When to use it

• Chats, queues, kitchen boards, live counters and dashboards.
• Any screen several people look at while the data changes.

Step by step

1. In a component, call app.live("table") inside useEffect and return what it gives you (the unsubscribe).
2. Read the rows with app.rows("table"). They refresh whenever any user or workflow changes the table.
3. For a custom query, put app.revision("table") in your effect's dependencies to refetch on change.

Code

The instructor desk in the booking app shows new bookings as they happen:

useEffect(() => (app ? app.live("booking") : undefined), [app]);
const bookings = app?.rows("booking") ?? [];

A filtered query that stays fresh:

const rev = app.revision("ticket");
useEffect(() => {
  void app.query("ticket", { where: { status: "open" }, sort: { field: "created_at", dir: "desc" } })
    .then((r) => setOpen(r.rows));
}, [app, rev]);

Topics: your own live messages

Publish from a workflow, subscribe over server-sent events:

// in a workflow written as code
await ctx.topics.publish("orders.ready", { id: row.id, table: row.table_label });

curl -N "https://<your-app-host>/__appbricx/topics/orders.ready/subscribe" \
  -H "Authorization: Bearer <data token>" -H "x-appbricx-data-api: 1"
# event: message
# data: {"id":"…","table":"T4"}

A workflow can also start when a topic gets a message. See workflows.

Watch events in the builder

Backend, Live streams change events and topic messages from dev or prod as they happen, and lists recent requests and errors. Agents get the same with the tail tool. See operating your app.

Gotchas

• Return the unsubscribe from your effect, or a screen keeps listening after it closes.
• Access still applies. A member following booking only receives their own rows.
• app.rows holds the newest 200 readable rows. Use app.query with paging for more.
• Events reach screens in the same process quickly; treat them as a refresh signal, not as a durable queue. Use a workflow for work that must happen.

Related

• Custom screens
• Workflows, schedules and webhooks
• SDK reference