Getting Started

You can use Loro in your application by using:

loro-crdt NPM package
loro Rust crate
loro-swift Swift package
loro-py Python package
loro-cs Community-maintained C# package
You can also find a list of examples in Loro examples in Deno.

You can use Loro Inspector to debug and visualize the state and history of Loro documents.

The following guide will use loro-crdt js package as the example.

Install

npm install loro-crdt
 
# Or
pnpm install loro-crdt
 
# Or
yarn add loro-crdt

If you’re using Vite, you should add the following to your vite.config.ts:

import wasm from "vite-plugin-wasm";
import topLevelAwait from "vite-plugin-top-level-await";
 
export default defineConfig({
  plugins: [...otherConfigures, wasm(), topLevelAwait()],
});

⚠️ DOMContentLoaded Timing Issue with Vite

When using Loro with Vite, be aware of module loading timing issues with DOM events:

Problem: The following code will cause nothing to load on the screen:

import { LoroDoc } from "loro-crdt";
 
document.addEventListener("DOMContentLoaded", () => {
  const doc = new LoroDoc();
  // Your code here...
});

Reason: This occurs because Vite loads ES modules asynchronously, and the WASM module initialization within loro-crdt also happens asynchronously. When you import at the top level but execute code inside DOMContentLoaded, the WASM module may not be fully initialized when the event fires, causing the application to fail silently.

Solutions:

Remove the event listener (recommended for most cases):

import {  } from "loro-crdt";
 
const  = new ();
// Your code here...

Use dynamic import inside the event listener:

.("DOMContentLoaded", async () => {
  const {  } = await import("loro-crdt");
  const  = new ();
  // Your code here...
});

The dynamic import ensures the module and its WASM dependencies are fully loaded before use.

If you’re using Next.js, you should add the following to your next.config.js:

module.exports = {
  webpack: function (config) {
    config.experiments = {
      layers: true,
      asyncWebAssembly: true,
    };
    return config;
  },
};

You can also use Loro directly in the browser via ESM imports. Here’s a minimal example:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>ESM Module Example</title>
  </head>
 
  <body>
    <div id="app"></div>
    <script type="module">
      import init, {
        LoroDoc,
      } from "https://cdn.jsdelivr.net/npm/loro-crdt@1.0.9/web/index.js";
 
      init().then(() => {
        const doc = new LoroDoc();
        const text = doc.getText("text");
      });
    </script>
  </body>
</html>

Introduction

It is well-known that syncing data/building realtime collaborative apps is challenging, especially when devices can be offline or part of a peer-to-peer network. Loro simplifies this process for you.

After you model your app state by Loro, syncing is simple:

import {  } from "loro-crdt";
const  = new ();
const  = new ();
 
//...operations on docA and docB
 
// Assume docA and docB are two Loro documents in two different devices
const  = .({ : "update" });
// send bytes to docB by any method
.();
// docB is now updated with all the changes from docA
 
const  = .({ : "update" });
// send bytes to docA by any method
.();
// docA and docB are now in sync, they have the same state

Saving your app state is also straightforward:

const  = new ();
.("text").(0, "Hello world!");
const  = .({ : "snapshot" });
// Bytes can be saved to local storage, database, or sent over the network

Loading your app state:

const  = new ();
.();

Loro also makes it easy for you to time travel the history and add version control to your app. Learn more about time travel.

.(); // Checkout the doc to the given version

Loro is compatible with the JSON schema. If you can model your app state with JSON, you probably can sync your app with Loro. Because we need to adhere to the JSON schema, using a number as a key in a Map is not permitted, and cyclic links should be avoided.

.(); // Get the JSON representation of the doc

Entry Point: LoroDoc

LoroDoc is the entry point for using Loro. You must create a Doc to use Map, List, Text, and other types and to complete data synchronization.

const  = new ();
const :  = .("text");
.(0, "Hello world!");
.(.()); // { "text": "Hello world!" }

Container

We refer to CRDT types such as List, Map, Tree, MovableList, and Text as Containers.

Here are their basic operations:

const  = new ();
const :  = .("list");
.(0, "A");
.(1, "B");
.(2, "C");
 
const :  = .("map");
// map can only has string key
.("key", "value");
(.()).({
  : ["A", "B", "C"],
  : { : "value" },
});
 
// delete 2 element at index 0
.(0, 2);
(.()).({
  : ["C"],
  : { : "value" },
});
 
// Insert a text container to the list
const  = .(0, new ());
.(0, "Hello");
.(0, "Hi! ");
 
(.()).({
  : ["Hi! Hello", "C"],
  : { : "value" },
});
 
// Insert a list container to the map
const  = .("test", new ());
.(0, 1);
(.()).({
  : ["Hi! Hello", "C"],
  : { : "value", : [1] },
});

Save and Load

Loro is a pure library and does not handle network protocols or storage mechanisms. It is your responsibility to manage the storage and transmission of the binary data exported by Loro.

To save the document, use doc.export({mode: "snapshot"}) to get its binary form. To open it again, use doc.import(data) to load this binary data.

const  = new ();
.("text").(0, "Hello world!");
const  = .({ : "snapshot" });
 
const  = new ();
.();
(.()).({
  : "Hello world!",
});

Exporting the entire document on each keypress is inefficient. Instead, use doc.export({mode: "update", from: VersionVector}) to obtain binary data for operations since the last export.

const  = new ();
.("text").(0, "Hello world!");
const  = .({ : "snapshot" });
let  = .();
.("text").(0, "✨");
const  = .({ : "update", :  });
 = .();
.("text").(0, "😶‍🌫️");
const  = .({ : "update", :  });
 
{
  /**
   * You can import the snapshot and the updates to get the latest version of the document.
   */
 
  // import the snapshot
  const  = new ();
  .();
  (.()).({
    : "Hello world!",
  });
 
  // import update0
  .();
  (.()).({
    : "✨Hello world!",
  });
 
  // import update1
  .();
  (.()).({
    : "😶‍🌫️✨Hello world!",
  });
}
 
{
  /**
   * You may also import them in a batch
   */
  const  = new ();
  .([, , ]);
  (.()).({
    : "😶‍🌫️✨Hello world!",
  });
}

If updates accumulate, exporting a new snapshot can quicken import times and decrease the overall size of the exported data.

You can store the binary data exported from Loro wherever you prefer.

Sync

Two documents with concurrent edits can be synchronized by just two message exchanges.

Below is an example of synchronization between two documents:

const  = new ();
const  = new ();
const :  = .("list");
.(0, "A");
.(1, "B");
.(2, "C");
// B import the ops from A
const :  = .({ : "update" });
// The data can be sent to B through the network
.();
(.()).({
  : ["A", "B", "C"],
});
 
const :  = .("list");
.(1, 1);
 
// `doc.export({mode: "update", from: version})` can encode all the ops from the version to the latest version
// `version` is the version vector of another document
const  = .({
  : "update",
  : .(),
});
.();
 
(.()).({
  : ["A", "C"],
});
(.()).(.());

Event

You can subscribe to the event from Containers.

LoroText and LoroList can receive updates in Quill Delta format.

The events will be emitted after a transaction is committed. A transaction is committed when:

doc.commit() is called.
doc.export(mode) is called.
doc.import(data) is called.
doc.checkout(version) is called.

Below is an example of rich text event:

// The code is from https://github.com/loro-dev/loro-examples-deno
const  = new ();
const  = .("text");
.(0, "Hello world!");
.();
let  = false;
.(() => {
  for (const  of .) {
    if (.. === "text") {
      (..).([
        {
          : 5,
          : { : true },
        },
      ]);
       = true;
    }
  }
});
.({ : 0, : 5 }, "bold", true);
.();
await new (() => (, 1));
().();

The types of events are defined as follows:

import { , , ,  } from "loro-crdt";
 
export interface LoroEventBatch {
  /**
   * How the event is triggered.
   *
   * - `local`: The event is triggered by a local transaction.
   * - `import`: The event is triggered by an import operation.
   * - `checkout`: The event is triggered by a checkout operation.
   */
  : "local" | "import" | "checkout";
  ?: string;
  /**
   * The container ID of the current event receiver.
   * It's undefined if the subscriber is on the root document.
   */
  ?: ;
  : LoroEvent[];
  : ;
  : ;
}
 
/**
 * The concrete event of Loro.
 */
export interface LoroEvent {
  /**
   * The container ID of the event's target.
   */
  : ;
  : ;
  /**
   * The absolute path of the event's emitter, which can be an index of a list container or a key of a map container.
   */
  : ;
}

Introduction to Loro Loro Document