Realtime Overview

Nuxt Zenstack can natively sync your client-side data with the database in real time. When enabled, your Nuxt application will receive Server-Sent Events (SSE) whenever data is created, updated, or deleted on the server.

The client composable (useZenstackRealtime) automatically listens to these events and updates the normalized store. As a result, all your useZenstackRead and useZenstackReadMany results are instantly updated across the entire application without any manual refetching.

Enabling Realtime

To enable realtime updates, you must configure both the module options and your exposure permissions:

1. Set realtime: true in your Nuxt config.
2. Add 'realtime' permission to the expose array for the models you want to be synced.

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@becem-gharbi/nuxt-zenstack'],
  zenstack: {
    realtime: true, // 1. Enable module-level realtime
    expose: {
      User: ['read', 'create', 'update', 'delete', 'realtime'], // 2. Enable for specific models
      Post: ['read', 'create', 'update', 'delete', 'realtime'],
    }
  }
})

CAUTION

If you omit 'realtime' from the expose array, mutation events for that model will not be broadcasted, even if realtime: true is set globally.

How it works under the hood

When realtime: true is configured:

1. The module wraps the ZenStack client with a mutation plugin (extendZenstackClient).
2. When a create, update, or delete operation succeeds, the server publishes an event containing the mutation type, model name, and affected IDs to a Pub/Sub system (by default, a Nitro hook).
3. The server maintains an SSE endpoint (/api/_zenstack/realtime) that pushes these events to connected clients.
4. Clients using useZenstackRealtime() receive the SSE messages and automatically update or remove the corresponding records in the normalized store.

NOTE

All realtime data broadcasted by the server strictly follows the Access Control policies (@@auth(), @@allow(), etc.) defined in your ZModel schema.