Y-Sweet: a realtime CRDT-based document store, backed by object storage

Y-Sweet is an open-source document store and realtime sync backend, built on top of the Yjs CRDT library.

Features

• Persists document data to S3-compatible storage, like Figma.
• Scales horizontally with a session backend model.
• Deploys as a native Linux process.
• Provides document-level access control via client tokens.
• Written in Rust with a focus on stability and performance.

Y-Sweet stack

The Y-Sweet server can be used by any Yjs app, or you can use our opinionated stack to integrate Yjs and Y-Sweet into a Next.js app.

• create-y-sweet-app, a command line tool to quickly create a Y-Sweet app.
• @y-sweet/sdk, a TypeScript library for interacting with y-sweet-server from your application backend.
• @y-sweet/client, a TypeScript library for syncing documents from a client to a Y-Sweet server.
• @y-sweet/react, a library of React hooks for connecting to a Y-Sweet server and manipulating Yjs docs.
• A debugger for exploring Yjs document and presence state.

Y-Sweet is MIT-licensed, and was created by Jamsocket.

Getting started

The easiest way to start a Y-Sweet project is with the create-y-sweet-app command line tool:

npx create-y-sweet-app@latest

For more information, check out our documentation.

Docs

• API docs
  • TypeScript client
  • React hooks
  • Document management SDK
• Y-Sweet on Jamsocket (managed service) docs
• Self Hosting and Running Locally

Examples

Explore our collaborative examples to help you get started or play with them live.

Examples using Yjs Editor Bindings

• CodeMirror Editor - see code | see live
• Monaco Editor - see code | see live
• BlockNote - see code | see live
• Quill Editor - see code | see live
• Slate Rich Text Editor - see code | see live

Usage

Check the vanilla js example for more details.

On the client

import * as Y from 'yjs';
import { createYjsProvider } from '@y-sweet/client';

// Create the Yjs doc and link it to the Y-Sweet server:
const doc = new Y.Doc();
const docId = 'my-doc-id';
createYjsProvider(doc, docId, '/api/my-auth-endpoint');

// Now use the doc like a normal Yjs doc!
let mySharedMap = doc.getMap('thing');
mySharedMap.set("foo", 123);

// Update your UI based on `mySharedMap` changes like this, for example:
mySharedMap.observe((event) => {
  event.keysChanged.forEach((key) => {
    // do whatever you want based on the detected change:
    yourUpdateFunction(key, mySharedMap.get(key));
  });
});

On the server

import { DocumentManager } from '@y-sweet/sdk';

// Pass in a CONNECTION_STRING, which you can get from a Y-Sweet service in the Jamsocket dashboard or from running npx y-sweet@latest serve locally
const manager = new DocumentManager(CONNECTION_STRING);

// create an endpoint that auths your user and returns a Y-Sweet client token
export async function POST(request) {
  // in a production app, you'd want to authenticate the user
  // and make sure they have access to the given doc
  const body = await request.json();
  const docId = body.docId;
  const clientToken = await manager.getOrCreateDocAndToken(docId);
  return Response.json(clientToken);
}

Running the Y-Sweet server locally

If you have npm, the fastest way to run a local server is with npx:

npx y-sweet@latest serve

This will download the Y-Sweet server if you do not already have it, and run it.

By default, y-sweet serve does not write data to disk. You can specify a directory to persist data to, like this:

npx y-sweet@latest serve /path/to/data

If the directory starts with s3://, Y-Sweet will treat it as an S3-compatible bucket path. Credentials are resolved through the AWS SDK default chain: static keys from the environment (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN), your local AWS profile (aws configure), an EKS service account (IRSA, via AWS_WEB_IDENTITY_TOKEN_FILE), EKS Pod Identity, or an EC2/ECS instance role — in that order. Static keys are optional; on Kubernetes with an IRSA-annotated service account, setting only Y_SWEET_STORE=s3://bucket/prefix (plus AWS_REGION) is enough. AWS_ENDPOINT_URL_S3 (for MinIO and other S3-compatible stores) and AWS_S3_USE_PATH_STYLE=true are still supported.

If the directory starts with gs://, Y-Sweet will treat it as a Google Cloud Storage bucket path, using Application Default Credentials: a service-account key file pointed to by GOOGLE_APPLICATION_CREDENTIALS, your local gcloud auth application-default login credentials, or the metadata server on GKE/GCE. On GKE with Workload Identity, binding the pod's Kubernetes service account to a Google service account that has access to the bucket is enough — set only Y_SWEET_STORE=gs://bucket/prefix.

In serve-doc (session backend) mode, STORAGE_BUCKET accepts a bare bucket name (S3, as before) or a gs://bucket value to select Google Cloud Storage.

Packages

Server

Package Manager	Name	Version	Path
npm	y-sweet		js-pkg/server
crates.io	y-sweet		crates/y-sweet
crates.io	y-sweet-core		crates/y-sweet-core

Client

Package Manager	Name	Version	Path
npm	@y-sweet/sdk		js-pkg/sdk
npm	@y-sweet/client		js-pkg/client
npm	@y-sweet/react		js-pkg/react
pypi	y-sweet-sdk		python/y_sweet_sdk

Hosted Y-Sweet on Jamsocket

You can run Y-Sweet on your own server, or you can run it on Jamsocket. Jamsocket is purpose-built to scale up sync backends like Y-Sweet, and allows you to bring your own storage.

You can try it out for free today by following our quickstart guide.