@smoothglue/sync-whiteboard v1.0.1

@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:

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: