Listening to Document Changes with Appwrite Realtime Subscriptions

Useful answer

Appwrite’s realtime subscription feature lets you receive live create, update, and delete events for any collection through a persistent WebSocket connection. By using the Appwrite JavaScript SDK you can set up a listener that automatically handles reconnection and heartbeats, so your UI updates instantly without polling.

How it works – a worked configuration

First, initialize the SDK with your Appwrite endpoint and project ID. Then call database.subscribe for the collection you want to watch. The callback receives a payload that includes the event type (create, update, delete) and the affected document. Remember to unsubscribe when the component that created the listener is destroyed to avoid memory leaks.

// 1. Import the SDK (adjust the path to your build system)
import { Appwrite } from "appwrite";

// 2. Create a client instance
const client = new Appwrite()
  .setEndpoint('https://your-appwrite-instance.com/v1') // <-- replace with your endpoint
  .setProject('YOUR_PROJECT_ID');                     // <-- replace with your project ID

// 3. Initialise the Database service
const database = new Appwrite.Database(client);

// 4. Subscribe to a collection (replace COLLECTION_ID)
const subscription = database.subscribe(
  'COLLECTION_ID',
  (response) => {
    // response.payload contains: { event: 'create'|'update'|'delete', document: {...}, collectionId: '...' }
    const { event, document, collectionId } = response.payload;
    console.log(`[${event}] Document ${document.$id} in collection ${collectionId}`);
    // Update your UI here based on the event type
  }
);

// 5. Cleanup – call when the listener is no longer needed (e.g., component unmount)
// subscription.unsubscribe();

Limits and practical considerations

• Concurrent subscriptions: Each Appwrite project defaults to a limit of 1000 simultaneous realtime subscriptions. Exceeding this limit causes the server to close new connections.
• Payload size: A single subscription message cannot exceed 1 MB. Large documents should be stored elsewhere (e.g., Appwrite Storage) and only a reference sent in the realtime event.
• Network resilience: The SDK automatically attempts to reconnect after a WebSocket drop, but you should still listen for the error event on the subscription to show fallback UI if reconnection fails repeatedly.

Common mistakes to avoid

• Forgetting to unsubscribe – leads to orphaned WebSocket connections and memory leaks, especially in single‑page apps where components mount and unmount frequently.
• Assuming the subscription provides the full document history on connect – it only streams changes that occur after the subscription is active.
• Using a single callback for multiple collections without checking collectionId in the payload, which can cause the wrong UI to update when collections share the same listener.

How to verify the setup

1. Run a local Appwrite stack (e.g., docker run -p 80:80 appwrite/appwrite:1.5) and create a project and a collection.
2. Insert the snippet above into a test HTML page, open the browser console, and add a document via the Appwrite console or API.
3. Observe a log line with the event type and document data. Stopping the Docker container briefly should trigger a reconnection attempt visible in the console.