Getting started

Start here

Colla gives your application a predictable document state machine and the OT primitives behind it.

This page answers two questions: what Colla provides and how to make the first edit.

What Colla provides

Colla combines immutable content and OT operations with a running Document state machine in one JavaScript package.

All JavaScript capabilities are exported from colla-ot. The Rust colla crate is the reference implementation for the data model, algebra, and canonical bytes.

Choose your workflow

The same package supports document state, immutable content operations, and protocol integration. Start with the workflow that matches your application.

Browser & NodeBuild a JavaScript app

Use a Document at the application boundary and connect your own transport.

→

Native & ServerBuild with Rust

Use typed constructors, native ownership, and reference OT algebra.

→

ArchitectureImplement a protocol

Understand canonical wire bodies and Snapshot/Update envelopes.

→

Install

For a copy-paste setup and first-run troubleshooting, see Install and make a first edit.

JavaScript

pnpm add colla-ot

colla-ot is ESM-only and supports Node.js 22+, Vite 5+, and Rollup 4+. Browser and Node entry points initialize the same WebAssembly core synchronously.

Rust

[dependencies]
colla = "0.3"

The crate supports Rust 1.81 or newer.

Make your first edit

import { Document, text } from 'colla-ot'

const document = Document.fromJS(text('Draft'))

const update = document.transact(tx => {
  tx.text([], t => t.retain(5).insert(' v2'))
})

console.log(document.get([])) // 'Draft v2' (direct read without handle overhead)
console.log(update.updateId)  // 1n

transact() updates visible content immediately and returns a pure Update object. Its canonical binary representation is available directly on update.bytes for transport. Acknowledgement happens after server acceptance (with cumulative semantics):

document.ack(update.updateId)

The boundary to remember

Colla owns

• Core Values and Changes
• OT algebra and deterministic rebasing
• Document state and events
• Snapshot and Update envelopes

Your application owns

• Transport and server ordering
• Sessions, auth, and retries
• History and storage
• Presence, cursors, and editor rendering

Next, read Document state or Values.