Build collaborative, stateful applications with the Ably Realtime Data Models SDK. Backed by your database, you can define live, observable data models in your client applications. You can also render live changes to data from your database in realtime.

Bring your own database

Store the data displayed in your frontend application in any database you choose or the one you already use.

Collaborative by default

Concurrently render live updates made by multiple users through your database.

Optimistic events

Deliver a super-responsive user experience. Show changes instantly, bypassing the wait for a network round trip or your database to confirm mutations. The Realtime Data Models SDK confirms changes behind the scenes, manages rollbacks, and flags any errors or conflicts to your app.

Backed by Ably

The Realtime Data Models SDK uses Ably’s fast, global message distribution network to update numerous clients across different regions with the freshest database state.

• Ably Realtime Data Models SDK
  • Overview
  • Development Status
  • Quickstart
    • Prerequisites
    • Installation and authentication
    • Instantiation
    • Creating a Model
  • Documentation and examples
  • Feedback

The Realtime Data Models SDK simplifies syncing application state from the database to the client in realtime. It constantly displays changes made simultaneously by others, creating a reactive, realtime, multiplayer application experience.

The Realtime Data Models SDK is a JavaScript (TypeScript) library that enables you to create live and observable data models in your frontend application. These models remain synchronized with the realtime state of your database model. You can easily integrate this SDK into your project regardless of your frontend framework preference. To learn how to use the SDK in a React/Next.js application, see examples.

Your backend publishes mutation events to Ably. The Realtime Data Models SDK updates your frontend app's local state. You can also pair the SDK with Ably's Database Connector to transmit transactional change events with your database mutations.

Note: Ably's realtime messaging platform integrates with the Realtime Data Models SDK to provide a fast, reliable, scalable global distribution network with seamless recovery.

The Models SDK is in the public alpha stage. It's designed primarily for experimental use and is currently unsuitable for production use. Your valuable feedback will help us focus on enhancements and resolve issues for upcoming versions.

To begin, you will need the following:

• An Ably account. You can sign up for free.
• An Ably API key. You can create API keys in an app within your Ably account.
  • The API key needs subscribe capabilities.

Install the Ably JavaScript SDK and the Realtime Data Models SDK:

npm install ably @ably-labs/models

Though you can test your installation and authentication with basic authentication, we strongly recommend token authentication for in production environments.

To instantiate the Realtime Data Models SDK, create an Ably client and pass it into the ModelsClient constructor:

import ModelsClient from '@ably-labs/models';
import { Realtime } from 'ably/promises';

const ably = new Realtime.Promise({ key: 'YOUR_ABLY_API_KEY' });
const modelsClient = new ModelsClient({ ably });

A Model represents a live, observable data model supported by the database.

To create a model, you need to:

1. Define the model's data structure in the frontend application.
2. Initialize the model.
3. Update the model based on events from the backend.
4. Determine how end-users can modify the model.

// this is the type for our model's data as represented in the frontend application
type Post = {
  id: number;
  text: string;
  comments: string[];
};

// a function used by the model to initialise with the correct data from your backend
async function sync() {
  const result = await fetch('/api/post');
  return result.json(); // e.g. { sequenceId: 1, data: { ... } }
}

// a function used by the model to merge a change event that is received and the existing model state
function merge(state: Post, event: OptimisticEvent | ConfirmedEvent) {
  return {
    ...state,
    text: event.data, // replace the previous post text field with the new value
  }
}

// a function that you might use to mutate the model data in your backend
async function updatePost(mutationId: string, content: string) {
  const result = await fetch(`/api/post`, {
    method: 'PUT',
    body: JSON.stringify({ mutationId, content }),
  });
  return result.json();
}

// create a new model instance called 'post' by passing the sync and merge functions
const model = modelsClient.models.get({
  name: 'post',
  channelName: 'models:posts',
  sync: sync,
  merge: merge,
})

// subscribe to live changes to the model data!
model.subscribe((err, post) => {
  if (err) {
    throw err;
  }
  console.log('post updated:', post);
});


// apply an optimistic update to the model
// confirmation is a promise that resolves when the optimistic update is confirmed by the backend.
// cancel is a function that can be used to cancel and rollback the optimistic update.
const [confirmation, cancel] = await model.optimistic({
    mutationId: 'my-mutation-id',
    name: 'updatePost',
    data: 'new post text',
})

// call your backend to apply the actual change
updatePost('my-mutation-id', 'new post text')

// wait for confirmation of the change from the backend
await confirmation;

For more information, see usage docs.

• Read the docs on Ably website.
• Browse the API Reference.
• Explore the examples.

The Models SDK is currently under development. We'd love to hear your feedback.