Guides

Lists that keep themselves current

live() gives a page the whole list at first, then again whenever a row in it changes, from anywhere, for exactly the rows the person may see.

app.live() is app.query() that keeps going. You get the whole list at once, and again every time a row in it is added, changed, removed, or stops being one this person may read.

const stop = app.live('job', { where: { status: 'open' }, orderBy: ['created_at', 'desc'], limit: 50 }, (rows) => {
  render(rows);
});

// When the list leaves the screen:
stop();

Changes reach the list wherever they were made: in this app, by your team in Claude Code, by an n8n workflow, by the server client. If a job moves to another customer, it leaves the first customer's list, and its messages leave too.

#What changed

The second argument says what changed since the last call, or null the first time and after a reconnect:

app.live('message', { where: { job_id: job.id }, orderBy: ['created_at', 'asc'] }, (rows, change) => {
  render(rows);
  if (change?.upserts.length) showMessage(`${change.upserts.length} new or changed`);
});

#When the server refuses a list

Pass an object to hear about a refusal, such as a column that does not exist or too many lists. The list stops.

app.live('job', { orderBy: ['title', 'asc'] }, {
  onRows: (rows) => render(rows),
  onError: (err) => showMessage(err.message),
});

#How it works

• One WebSocket serves every live list on a client. It is opened on the first live(), reconnects by itself, and after a reconnect sends each list whole again rather than replaying what was missed.
• The hub re-runs each list as the person, so the database applies their read rule. Nothing is filtered in your page.
• Each list holds up to 200 rows, and a connection up to 20 lists. An account can have 200 connections open at once on Pro and 1,000 on Embedded.
• While a list is open in a browser, the connection also tells the hub whether the tab is in front. If the account sends reply emails (switched on per app, on the app's page in the hub), someone looking at the app isn't emailed about a reply they can already see; a tab left open behind others doesn't count as looking.

#Outside a browser

In Node 22 and later there is a global WebSocket. On older Node, pass one, for example from the ws package:

const node = createAppClient({ publishableKey: 'pk_...', WebSocket });