Network and Storage Providers¶
Collabs documents don’t come with networking or storage built-in. Instead, you should configure network and storage providers. These keep your Collabs in sync with remote collaborators and persistent storage.
Our providers are inspired by Yjs’s providers and Automerge-Repo.
Collabs Providers¶
We publish several providers alongside Collabs. We already saw three in the Quick Start; a complete list is below.
To use a provider, you typically construct a single instance per app. Then you can use its subscribe and unsubscribe methods to work with as many documents as you like.
Each provider uses docIDs (arbitrary strings) to keep track of which documents are supposed to be kept in sync. For example, when using our Websocket client and server, documents on different devices that subscribe to the same docID will be kept in sync via the server.
All of our providers are designed to work well together. E.g., if you subscribe a document to both @collabs/indexeddb and @collabs/ws-client, then updates loaded from IndexedDB will be forwarded to the WebSocket server and vice-versa. That way, all copies of the document stay in sync.
@collabs/ws-client¶
WebSocketNetwork is a network provider that syncs Collabs documents with a central server using WebSockets. This is an easy way to collaborate with other users: each update is sent to the server, which echoes it to other users listening on the same docID and also stores it for later.
The @collabs/ws-server package contains the server. You can construct its WebSocketNetworkServer in a Node.js app or run the collab-ws-server command.
@collabs/tab-sync¶
TabSyncNetwork is a network provider that shares updates across local tabs using BroadcastChannel. That way, a user with multiple tabs open sees their changes sync quickly, even when offline.
@collabs/indexeddb¶
IndexedDBDocStore is a storage provider that stores Collabs documents in IndexedDB. That way, your app can load documents quickly, even when offline. Adding IndexedDB storage is one step towards making your app local-first.
@collabs/local-storage¶
LocalStorageDocStore is a storage provider that stores Collabs documents in localStorage. That way, your app can load documents quickly, even when offline.
Note that you will be subject to localStorage’s small storage quotas.
3rd-Party Providers¶
If you publish your own provider (WebRTC networking, file storage, ??), let us know in our Matrix room and we can list it here.
Manual¶
You can also manually manage document updates, using the methods and events on CRuntime / AbstractDoc. This is how providers work internally. See Updates and Sync for more info.
Manual update management (or writing custom providers) is often necessary for more complex apps, since our published providers are simple instead of flexible. However, you may still find it useful to read or fork our providers’ source code, which contains thorough comments.
Next Steps¶
You now know everything you need to begin making Collabs apps! Our app template (described in the Quick Start) is a good starting point.
The rest of the Guide gives more info about working with Collabs. Continue with Built-in Collabs.