@smoothglue/sync-whiteboard

A real-time collaborative whiteboard server designed to provide a realtime, collaborative whiteboard experience for frontends integrated with tldraw. It functions as a microservice, handling websocket connections to sync shared whiteboard edits in real-time using tldraw's sync-core library.

Overview

The core responsibilities of this service include:

• Managing WebSocket connections for real-time synchronization of whiteboard edits.
• Facilitating data persistence (snapshots) via a backend API.
• Handling storage of assets (like images or videos) via a backend API.

Features

• Real-time Collaboration: Leverages WebSockets and @tldraw/sync-core for multi-user interaction on a shared whiteboard via Fastify and @fastify/websocket.
• Snapshot Persistence: Delegates saving and loading whiteboard state snapshots to a configurable backend service. The development environment includes a mock backend for this.
• Asset Handling: Delegates uploading and retrieving large binary assets to a configurable backend service. The development environment includes a mock backend for this.

Architecture

This service is designed as a NodeJS microservice that connects to client applications using tldraw via WebSockets for real-time data synchronization. It relies on external services (configurable via environment variables) for persisting snapshots and storing assets.

Installation

npm install @smoothglue/sync-whiteboard
# or
yarn add @smoothglue/sync-whiteboard

Configuration

The @smoothglue/sync-whiteboard server is configured entirely through the environment variables listed below:

| Environment Variable | Description | Default Value | Required | | :------------------------------- |:---------------------------------------------------------------------------------------------------------------| :------------ |:---------| | SWB_PORT | The port on which the server will listen. | 5858 | No | | SWB_HOST | The host address the server will bind to. | 0.0.0.0 | No | | SWB_LOG_LEVEL | The minimum log level for messages (e.g, fatal, error, warn, info, debug). | info | No | | SWB_SNAPSHOT_STORAGE_URL | Crucial: The base URL for the service responsible for persisting tldraw room states. | (None) | Yes | | SWB_ASSET_STORAGE_URL | Crucial: The base URL for the service responsible for storing and retrieving tldraw assets (e.g., images). | (None) | Yes | | SWB_SAVE_INTERVAL_MS | The interval (in milliseconds) the server periodically checks for and saves updated room snapshots. | 5000 | No |

Usage

This package provides a server that can be integrated into your application or run as a standalone service.

Integrating with your Application

You can require/import the package directly into your Node.js application. Upon import, the server will attempt to start, binding to the host and port configured via environment variables.

// Example application's entry point: (e.g., app.js or index.js)
// Imports the package, which initializes and starts the sync server.
require('@smoothglue/sync-whiteboard');

Running as a Standalone Service (e.g., in Docker)

To run the @smoothglue/sync-whiteboard server as a standalone process, execute its main entry point. This is typically done within a Docker container where environment variables are easily managed.

From your containerized Node.js environment with dependencies installed, your CMD or ENTRYPOINT in the Dockerfile would look like this:

# Dockerfile snippet example
# ... (setting up Node.js, copying package.json, running npm install)
# The 'dist/server.js' file is the compiled entry point of the @smoothglue/sync-whiteboard package.
CMD ["node", "node_modules/@smoothglue/sync-whiteboard/dist/server.js"]

Development Environment (Docker)

This project includes a Docker-based development environment configured in dev-env/docker-compose.yml. This makes it easy to run the sync-whiteboard server along with its dependencies (mock backend API, database, object storage) and a mock frontend client.

Prerequisites:

• Docker (https://www.docker.com/get-started)
• Docker Compose (https://docs.docker.com/compose/install/)

Configuration (Optional):

If you wish to alter the default sync-whiteboard server configuration, refer to the following steps.

1. Navigate to the dev-env directory:

   cd sync-whiteboard/dev-env

2. Copy env.example to .env and adjust settings as needed. This file configures services like the database and object storage services expressed within docker-compose.yml. For sync-whiteboard specific settings, see the Configuration section above.

Running the Environment:

1. From the dev-env directory, run:

   docker-compose up --build

Services:

The Docker Compose setup starts the following services:

| Service Name | Description | Accessible At (Host) | | :------------------- | :------------------------------------------------------------------- |:------------------------------------------------| | sync-whiteboard | The main Node.js sync server for real-time whiteboard collaboration. | ws://localhost:5858 | | mock-backend | A Flask-based API simulating backend storage for snapshots & assets. | http://localhost:5001 | | postgres | PostgreSQL database for the mock backend's snapshot storage. | localhost:5433 | | minio | MinIO object storage for the mock backend's asset storage. | http://localhost:9001 | | mock-frontend | A simple Vite+React client for testing the whiteboard functionality. | http://localhost:8080 |