SyncedStore

https://syncedstore.org/
Admin
SyncedStore is a library for building distributed, real-time collaborative web applications that...
Tokens:7,159
Snippets:80
Trust Score:7.2
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install SyncedStore and Yjs

Source: https://syncedstore.org/docs/basics/installation

Install the core SyncedStore library and the required Yjs dependency.

```bash
npm install --save @syncedstore/core  
  
# SyncedStore builds on top of yjs, install that too:  
npm install --save yjs  
```

--------------------------------

### Install Optional Dependencies

Source: https://syncedstore.org/docs/basics/installation

Install optional helper libraries for WebRTC synchronization and React integration.

```bash
# For syncing over webrtc:  
npm install --save y-webrtc  
  
# If you use React, install the helper library:  
npm install --save @syncedstore/react  
```

--------------------------------

### Vue 3 Todo App Example

Source: https://syncedstore.org/docs/vue

A complete example of a collaborative Todo application using Vue3 and SyncedStore. It demonstrates creating, updating, and deleting todos, with real-time synchronization.

```vue
<template>
<main id="app">
<h1>Todo Vue</h1>
<input
class="new-todo"
autofocus
autocomplete="off"
placeholder="What needs to be done?"
v-model="newTodo"
@keyup.enter="addTodo"
/>
<ul class="todo-list">
<li
v-for="todo in store.todos"
class="todo"
>
<div class="view">
<label>
<input class="toggle" type="checkbox" v-model="todo.completed" />
{{ todo.title }}
</label>
<button class="destroy" @click="removeTodo(todo)">Delete</button>
</div>
</li>
</ul>
</main>
</template>

<script>
import { store } from "./store";
import { ref } from "vue";
import * as Vue from "vue";
import { enableVueBindings } from "@syncedstore/core";

// make SyncedStore use Vuejs internally
enableVueBindings(Vue);

```

--------------------------------

### Basic Todo App with SyncedStore in React

Source: https://syncedstore.org/docs/react

This example demonstrates a basic todo application using SyncedStore and React. It shows how to import the store, use the useSyncedStore hook, and manage todo items.

```typescript
import React from "react";
import { useSyncedStore } from "@syncedstore/react";
import { store } from "./store";
  

export default function App() {
const state = useSyncedStore(store);
  
return (
<div>
<p>Todo items:</p>
<ul>
{state.todos.map((todo, i) => {
return (
<li key={i} style={{ textDecoration: todo.completed ? "line-through" : "" }}>
<label>
<input type="checkbox" checked={todo.completed} onClick={() => (todo.completed = !todo.completed)} />
{todo.title}
</label>
</li>
);
})}
</ul>
<input
placeholder="Enter a todo item and hit enter"
type="text"
onKeyPress={(event) => {
if (event.key === "Enter") {
const target = event.target as HTMLInputElement;
// Add a todo item using the text added in the textfield
state.todos.push({ completed: false, title: target.value });
target.value = "";
}
}}
style={{ width: "200px", maxWidth: "100%" }}
/>
</div>
)
```

--------------------------------

### Enable Vue Bindings

Source: https://syncedstore.org/docs/vue

Call `enableVueBindings` once during store setup to integrate SyncedStore with Vue3's reactivity. Ensure Vue is imported.

```typescript
import * as Vue from "vue";
import { enableVueBindings } from "@syncedstore/core";

enableVueBindings(Vue);

```

--------------------------------

### TipTap Editor with SyncedStore Integration

Source: https://syncedstore.org/docs/advanced/richtext

This example demonstrates how to configure a TipTap editor to use SyncedStore for collaborative editing. It sets up necessary extensions like Collaboration and CollaborationCursor, assigning random user names and colors.

```typescript
import React, { useState, useCallback, useEffect } from "react";
import { store, webrtcProvider } from "./store";
  
import { useEditor, EditorContent } from "@tiptap/react";
import StarterKit from "@tiptap/starter-kit";
import Placeholder from "@tiptap/extension-placeholder";
import Collaboration from "@tiptap/extension-collaboration";
import CollaborationCursor from "@tiptap/extension-collaboration-cursor";
  
const colors = ["#958DF1", "#F98181", "#FBBC88", "#FAF594", "#70CFF8", "#94FADB", "#B9F18D"];
const names = ["Lea Thompson", "Cyndi Lauper", "Tom Cruise", "Madonna"];
  
const getRandomElement = (list) => list[Math.floor(Math.random() * list.length)];
const getRandomColor = () => getRandomElement(colors);
const getRandomName = () => getRandomElement(names);
  
export default () => {
const editor = useEditor({
extensions: [
StarterKit,
Placeholder.configure({
placeholder: "Write something …",
}),
Collaboration.configure({
fragment: store.fragment,
}),
CollaborationCursor.configure({
provider: webrtcProvider,
user: { name: getRandomName(), color: getRandomColor() },
}),
],
});
  
return (
<div className="editor">
<MenuBar editor={editor} />
<EditorContent editor={editor} />
</div>
);
};
```

--------------------------------

### Implement Todo Logic in Svelte Component

Source: https://syncedstore.org/docs/svelte

Example of using a SyncedStore-backed Svelte store within a component to manage list items.

```html
<script>
import { svelteStore } from "./store.js";
  

let newTodo = "";
  

const addTodo = () => {
const value = newTodo && newTodo.trim();
  

if (!value) {
return;
}
$svelteStore.todos.push({
title: value,
completed: false
});
newTodo = "";
};
  

const removeTodo = todo => {
$svelteStore.todos.splice($svelteStore.todos.indexOf(todo), 1);
};
</script>
  

<main id="app">
<h1>Todo Svelte</h1>
<form on:submit|preventDefault={addTodo}>
<input
class="new-todo"
autocomplete="off"
placeholder="What needs to be done?"
bind:value={newTodo}
/>
</form>
<ul class="todo-list">
{#each $svelteStore.todos as todo}
<li class="todo">
```

--------------------------------

### Enable MobX Bindings for SyncedStore

Source: https://syncedstore.org/docs/advanced/mobx

Call `enableMobxBindings` once during store setup to integrate SyncedStore with MobX. This allows the use of MobX functionalities like reactions and autorun.

```typescript
import * as mobx from "mobx";
import { enableMobxBindings } from "@syncedstore/core";

enableMobxBindings(mobx);
```

--------------------------------

### Use SyncedText for Collaborative String Editing (Nested)

Source: https://syncedstore.org/docs/advanced/text

Instantiate SyncedText to enable simultaneous collaborative editing of strings. This example shows how to add a SyncedText property to an existing object within the store.

```typescript
import { SyncedText } from "@syncedstore/core";  
  
export const store = syncedStore({ myObject: {} });  
store.myObject.myText = new SyncedText("hello");  
  
// now, other users can simultaneously edit text by calling `insert` and `delete` methods  
  
store.myObject.myText.insert(0, "My name is Bob, ");  

```

--------------------------------

### Initialize a SyncedStore

Source: https://syncedstore.org/docs/basics/installation

Create a store instance and configure a WebRTC provider for automatic synchronization.

```typescript
import { syncedStore, getYjsDoc } from "@syncedstore/core";  
import { WebrtcProvider } from "y-webrtc";  
  
// (optional, define types for TypeScript)  
type Vehicle = { color: string; brand: string };  
  
// Create your SyncedStore store  
export const store = syncedStore({ vehicles: [] as Vehicle[] });  
  
// Get the Yjs document and sync automatically using y-webrtc  
const doc = getYjsDoc(store);  
const webrtcProvider = new WebrtcProvider("my-document-id", doc);  
```

--------------------------------

### Initialize and Manipulate SyncedStore in JavaScript

Source: https://syncedstore.org/docs/basics/example

Demonstrates creating a store with an array and an object, and updating them via DOM event handlers.

```javascript
import { observeDeep } from "@syncedstore/core";
import { store } from "./store";
  

const root = document.getElementById("app");
  

// Display the contents of the store
const jsonView = document.createElement("pre");
jsonView.innerText = JSON.stringify(store, undefined, 2);
root.appendChild(jsonView);
  

// Add a button to add some values to store.myArray
const addElementBtn = document.createElement("button");
addElementBtn.innerText = "Add values to array";
addElementBtn.onclick = () => {
// Add an object to the array
store.myArray.push({ property: "value" });
  

// Add a random number between 0 and 100 to the array
store.myArray.push(Math.floor(Math.random() * 100));
};
root.appendChild(addElementBtn);
  

// Add a button to set a property on store.myObject
  

// Which property to change?
const inputPropertyName = document.createElement("input");
inputPropertyName.value = "myProp";
root.appendChild(inputPropertyName);
  

// What value to set to the property?
const inputPropertyValue = document.createElement("input");
inputPropertyValue.value = "myValue";
root.appendChild(inputPropertyValue);
  

// Add the actual button to change a property
const setPropertBtn = document.createElement("button");
```

--------------------------------

### Basic Store Operations

Source: https://syncedstore.org/

Demonstrates how to add items to a collection and update properties within a SyncedStore object.

```javascript
// add a todo  
store.todos.push({ completed: false, title: "Get groceries" });  
  
// set todo to completed  
store.todos[0].completed = true;  
```

--------------------------------

### enableMobxBindings

Source: https://syncedstore.org/docs/api

Enables MobX integration for reactivity.

```APIDOC
## enableMobxBindings

### Description
Enable MobX integration.

### Parameters
- **mobx** (any) - Required - An instance of mobx.
```

--------------------------------

### Configure y-webrtc provider

Source: https://syncedstore.org/docs/sync-providers

Initializes a peer-to-peer connection using WebRTC for document synchronization.

```javascript
import { syncedStore, getYjsDoc } from "@syncedstore/core";  
import { WebrtcProvider } from "y-webrtc";  
  
export const store = syncedStore({ arrayData: [] });  
  
const doc = getYjsDoc(store);  
const webrtcProvider = new WebrtcProvider("my-document-id", doc);  
```

--------------------------------

### enableVueBindings

Source: https://syncedstore.org/docs/api

Enables Vue3 integration for reactivity.

```APIDOC
## enableVueBindings

### Description
Enable Vue3 integration.

### Parameters
- **vue** (any) - Required - An instance of Vue or Vue reactivity.
```

--------------------------------

### Understanding SyncedStore Internals

Source: https://syncedstore.org/docs/advanced/yjs

Explains the key abstractions SyncedStore provides over Yjs, simplifying direct data manipulation and change observation.

```APIDOC
## Understanding the SyncedStore internals

### Description
SyncedStore simplifies Yjs usage by abstracting away direct Yjs data types and manual observation.

### Key Abstractions

1.  **Plain JavaScript Objects and Arrays**: Instead of using Yjs-specific types like `Y.Map` and `Y.Array`, SyncedStore allows you to work with standard JavaScript objects and arrays. Changes are automatically translated to Yjs operations.
    *   **Example**: `store.outer.inner.property = value` (SyncedStore) instead of `doc.getMap("outer").get("inner").set("property", "value")` (Yjs).

2.  **Automatic Change Observation**: SyncedStore integrates with reactive programming libraries (like MobX, Vue's reactive model, or React's `useSyncedStore` hook) to automatically observe changes in the store. You do not need to manually call `.observe`.
    *   **Example**: Wrap your code in `autorun` or use `useSyncedStore` (React) to automatically react to all used values from the store.
```

--------------------------------

### Configure y-indexeddb with y-webrtc

Source: https://syncedstore.org/docs/sync-providers

Combines offline persistence via IndexedDB with real-time synchronization via WebRTC.

```javascript
import { syncedStore, getYjsDoc } from "@syncedstore/core";  
import { WebrtcProvider } from "y-webrtc";  
import { IndexeddbPersistence } from "y-indexeddb";  
  
export const store = syncedStore({ arrayData: [] });  
  
const doc = getYjsDoc(store);  
const webrtcProvider = new WebrtcProvider("my-document-id", doc);  
const provider = new IndexeddbPersistence("my-document-id", doc);  
```

--------------------------------

### Define Syncedstore with Boxed Values

Source: https://syncedstore.org/docs/advanced/boxed

Import `Box` and `boxed` from `@syncedstore/core`. Initialize the store with an array of `Box<Todo>[]` to enable boxed values. Use `boxed()` to wrap objects added to this array.

```typescript
import { syncedStore, Box, boxed } from "@syncedstore/core";

export const store = syncedStore(doc, { todos: [] as Box<Todo>[] });

// ...

store.todos.push(boxed({ title: "groceries", completed: false }));

// Use `value` to get the contents of the box
const completed = store.todos[0].value.completed;
```

--------------------------------

### Configure y-websocket provider

Source: https://syncedstore.org/docs/sync-providers

Connects to a WebSocket server for centralized document synchronization.

```javascript
import { syncedStore, getYjsDoc } from "@syncedstore/core";  
import { WebsocketProvider } from "y-websocket";  
  
export const store = syncedStore({ arrayData: [] });  
  
const doc = getYjsDoc(store);  
  
// Start a y-websocket server, e.g.: HOST=localhost PORT=1234 npx y-websocket-server  
  
const wsProvider = new WebsocketProvider("ws://localhost:1234", "my-roomname", doc);  
```

--------------------------------

### Create a Svelte Store from SyncedStore

Source: https://syncedstore.org/docs/svelte

Use svelteSyncedStore to wrap a SyncedStore instance, allowing it to be used as a standard Svelte store.

```javascript
import { syncedStore, getYjsValue } from "@syncedstore/core";  
import { svelteSyncedStore } from "@syncedstore/svelte";  
  
// Create your SyncedStore store  
const todoStore = syncedStore({ todos: [] });  
  
// Create Svelte Store for use in your components.  
// You can treat this like any other store, including `bind`.  
export const store = svelteSyncedStore(todoStore);
```

--------------------------------

### ProseMirror Integration with SyncedStore

Source: https://syncedstore.org/docs/advanced/richtext

This snippet shows how to integrate SyncedStore with ProseMirror using the y-prosemirror plugin. It initializes a Y.Doc, creates a SyncedStore with an 'xml' fragment, and configures the ProseMirror EditorState to use the ySyncPlugin.

```typescript
import syncedStore from "@syncedstore/core";  
import { ySyncPlugin } from "y-prosemirror";  
  
const doc = new Y.Doc();  
export const store = syncedStore({ fragment: "xml" });  
  
// When you set up your ProseMirror instance,  
// hook up store.fragment to the y-prosemirror plugin  
EditorState.create({  
  plugins: [  
    ySyncPlugin(store.fragment),  
    // ... other plugins  
  ],  
  // ... remaining prosemirror setup  
});  
```

--------------------------------

### Add and Complete a Todo Item

Source: https://syncedstore.org/docs

Use this snippet to add new todo items to the store or mark existing ones as completed. Ensure the store object is initialized before use.

```javascript
// add a todo  
store.todos.push({ completed: false, title: "Get groceries" });  
  
// set todo to completed  
store.todos[0].completed = true;
```

--------------------------------

### syncedStore

Source: https://syncedstore.org/docs/api

Creates a new SyncedStore store based on a provided shape.

```APIDOC
## syncedStore

### Description
Create a SyncedStore store.

### Parameters
- **shape** (T) - Required - An object that describes the root types of the store.
- **doc** (Doc) - Optional - A Y.Doc to use as the backing system.

### Response
- **Returns** (MappedTypeDescription<T>) - A SyncedStore store.
```

--------------------------------

### Use SyncedText at the Root of a Store

Source: https://syncedstore.org/docs/advanced/text

Define a SyncedText instance directly at the root of your store for immediate access. The instance is initially empty and populated as users add text.

```typescript
import { SyncedText } from "@syncedstore/core";  
  
export const store = syncedStore({ myText: "text" });  
  
// now, other users can simultaneously edit text by calling `insert` and `delete` methods  
  
store.myText.insert(0, "Hello world");  

```

--------------------------------

### getYjsDoc

Source: https://syncedstore.org/docs/api

Accesses the internal Yjs Doc from a store.

```APIDOC
## getYjsDoc

### Description
Access the internal Yjs Doc.

### Parameters
- **store** (T) - Required - A store returned by syncedStore.

### Response
- **Returns** (Y.Doc) - The Yjs doc (Y.Doc) underneath.
```

--------------------------------

### Accessing Yjs Objects

Source: https://syncedstore.org/docs/advanced/yjs

Demonstrates how to use the `getYjsValue` function to retrieve the underlying Yjs data structures from SyncedStore objects.

```APIDOC
## `getYjsValue(object: any)`

### Description
Retrieves the underlying Yjs data structure (Y.Doc, Y.Map, or Y.Array) associated with a given SyncedStore object.

### Parameters
#### Path Parameters
- **object** (any) - Required - A value from the SyncedStore store.

### Return Value
- **Y.Doc** - If `object` is the store itself.
- **Y.Array** - If `object` is an array.
- **Y.Map** - If `object` is an object.

### Request Example
```javascript
import { getYjsValue } from "@syncedstore/core";

// Assuming 'state' is your SyncedStore instance
const doc = getYjsValue(state);

// Assuming 'state.todos' is an array in your store
const array = getYjsValue(state.todos);

// Assuming 'state.todos[0]' is an object in your store
const map = getYjsValue(state.todos[0]);
```

### Response Example
```json
{
  "doc": "Y.Doc object",
  "array": "Y.Array object",
  "map": "Y.Map object"
}
```
```

--------------------------------

### React Component with MobX Observer and SyncedStore

Source: https://syncedstore.org/docs/advanced/mobx

Use the `observer` pattern from `mobx-react-lite` for React components interacting with SyncedStore. This eliminates the need for the `useSyncedStore` hook.

```typescript
import React from "react";
import { store } from "./store";
import { observer } from "mobx-react-lite";
import * as mobx from "mobx";
import { enableMobxBindings } from "@syncedstore/core";
  

// enable mobx bindings
enableMobxBindings(mobx);
  

// use the observer pattern from mobx-react-lite.
export const App = observer(() => {
return (
<div>
<p>Todo items:</p>
<ul>
{store.todos.map((todo, i) => {
return (
<li key={i} style={{ textDecoration: todo.completed ? "line-through" : "" }}>
<label>
<input type="checkbox" checked={todo.completed} onClick={() => (todo.completed = !todo.completed)} />
{todo.title}
</label>
</li>
);
})}
</ul>
<input
placeholder="Enter a todo item and hit enter"
type="text"
onKeyPress={(event) => {
if (event.key === "Enter") {
const target = event.target as HTMLInputElement;
// Add a todo item using the text added in the textfield
store.todos.push({ completed: false, title: target.value });
target.value = "";
}
}} />
</div>
);
});
```

--------------------------------

### observeDeep

Source: https://syncedstore.org/docs/api

Registers a listener for changes to an object or its nested properties.

```APIDOC
## observeDeep

### Description
Register a listener for when any changes to object or its nested objects occur.

### Parameters
- **object** (any) - Required - The synced object (store, object, map, or Yjs value to observe)
- **handler** (() => void) - Required - The callback to be raised.

### Response
- **Returns** (fn) - A function to dispose (unregister) the handler.
```

--------------------------------

### Store Plain Strings in SyncedStore

Source: https://syncedstore.org/docs/advanced/text

Use this method to store strings that will be shared across users. Note that simultaneous modification of the same string is not supported with this approach.

```typescript
export const store = syncedStore({ myArray: [], myObject: {} });  
store.myArray.push("first string");  
store.myObject.property = "string value";  

```

--------------------------------

### Accessing Yjs objects with getYjsValue

Source: https://syncedstore.org/docs/advanced/yjs

Demonstrates how to retrieve Yjs internal objects from a SyncedStore state using the getYjsValue function.

```typescript
import React from "react";
import { useSyncedStore } from "@syncedstore/react";
import { boxed, getYjsValue } from "@syncedstore/core";
import { store } from "./store"; // the store we defined above
import { ObjectInspector } from "react-inspector";
  

export default function App() {
const state = useSyncedStore(store);
  

const doc = getYjsValue(state);
const array = getYjsValue(state.todos);
const map = state.todos.length ? getYjsValue(state.todos[0]) : undefined;
  

return (
<div>
<p>Todo items:</p>
<p>{JSON.stringify(state)}</p>
  

<ObjectInspector data={{ doc, array, map }} />
<br />
<div>
<button
onClick={() => {
state.todos.push({ title: "This is a todo", completed: false });
}}
>
Add a todo
</button>
</div>
</div>
);
}
```

--------------------------------

### Using the useSyncedStore Hook

Source: https://syncedstore.org/docs/react

The useSyncedStore hook takes the store as a parameter and automatically detects which properties of the state are used in the React component for optimized re-renders.

```javascript
const state = useSyncedStore(store);
```

--------------------------------

### Define Store Shape

Source: https://syncedstore.org/docs/basics/installation

Define the structure of the collaborative data using the shape object.

```javascript
const shape = {  
  exampleArrayData: [],  
  exampleObjectData: {},  
  exampleXMLData: "xml",  
  exampleTextData: "text",  
};  
const store = syncedStore(shape);  
```

--------------------------------

### areSame

Source: https://syncedstore.org/docs/api

Checks whether two objects represent the same value, accounting for Proxy wrapping.

```APIDOC
## areSame

### Description
Check whether two objects represent the same value. A strict equality (===) check doesn't always work, because SyncedStore can wrap the object with a Proxy.

### Parameters
- **objectA** (any) - Required - Object to compare with objectB
- **objectB** (any) - Required - Object to compare with objectA

### Response
- **Returns** (boolean) - true if they represent the same object, false otherwise.
```

--------------------------------

### Add Boxed Item in React Component

Source: https://syncedstore.org/docs/advanced/boxed

In a React component using `@syncedstore/react`, import `boxed` and use it when pushing new items to a store array defined with `Box`.

```typescript
import React from "react";
import { useSyncedStore } from "@syncedstore/react";
import { boxed } from "@syncedstore/core";
import { store } from "./store"; // the store we defined above

export default function App() {
  const state = useSyncedStore(store);

  return (
    <div>
      <p>Todo items:</p>
      {JSON.stringify(state, undefined, 2)}

      <div>
        <button
          onClick={() => {
            state.todos.push(boxed({ title: "This is a todo", completed: false }));
          }}
        >
          Add a boxed item
        </button>
        <br />
        <button
          disabled={state.todos.length === 0}
          onClick={() => {
            state.todos.splice(
              0,
              1,
              boxed({
                title: state.todos[0].value.title,
                completed: !state.todos[0].value.completed,
              })
            );
          }}
        >
          Edit first item (replace)
        </button>
```

--------------------------------

### Update Boxed Values by Replacement

Source: https://syncedstore.org/docs/advanced/boxed

To update a boxed value, replace the entire item in the array using `splice`. Directly modifying properties of a boxed item (e.g., `store.todos[0].completed = true;`) will not sync.

```typescript
// GOOD:
store.todos.splice(0, 1, boxed({ title: "groceries", completed: true }));

// BAD, this won't sync as individual properties of a boxed item are not collaborative
store.todos[0].completed = true;
```
Tokens:
Raw