---
name: bijection-prosemirror-sync
description: "Evaluate and integrate the Collaborative Text Editor component with Bijection."
---

# Collaborative Text Editor

Collaborative rich-text editing

- Package: @bijectionhq/prosemirror-sync
- Category: Collaboration
- Status: Included
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/prosemirror-sync/tree/d946a7813ddc721aefa0adc9de7b3e128645a451
- Upstream: https://github.com/convex/prosemirror-sync/tree/6d6009ebf5bc208134780c8d74fc034f9fceb271
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/prosemirror-sync

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/prosemirror-sync.git
cd prosemirror-sync
git checkout d946a7813ddc721aefa0adc9de7b3e128645a451
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This source is included in Bijection's workspace. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @convex-dev/prosemirror-sync. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Collaborative Text Editor Sync. Follow the installation and configuration steps exactly.

# Collaborative Text Editor Sync

## Instructions

This component adds collaborative document editing to your Convex app using ProseMirror's operational transformation engine. It provides React hooks for Tiptap and BlockNote editors that automatically sync document changes between clients through your Convex database. The component handles conflict resolution, debounced snapshots for performance, and server-side document transformations for AI integration.

### Installation

```bash
npm install @convex-dev/prosemirror-sync
```

Current npm version: `@convex-dev/prosemirror-sync@0.2.7`

## Use cases

- **Building a collaborative document editor** where multiple users need to edit the same document simultaneously across different devices or browser tabs
- **Adding rich text editing to multi-user apps** like project management tools, note-taking apps, or content management systems that require real-time collaboration
- **Integrating AI-powered document features** where you need to programmatically modify documents server-side while users are actively editing
- **Creating offline-capable editors** that allow users to start editing new documents before connecting to the server and sync changes when back online
- **Building document-centric workflows** where you need the document data stored alongside other app data in your Convex database for queries and relationships

## How it works

You install the component in your `convex.config.ts` file, then expose the sync API through a Convex function that calls methods like `getSnapshot`, `submitSteps`, and `latestVersion` from the `ProsemirrorSync` class. The component uses operational transformations to safely merge concurrent edits between clients.

On the frontend, you use either `useBlockNoteSync` or `useTiptapSync` React hooks that handle document fetching, real-time syncing via a Tiptap extension, and local state management. The hooks provide a `create()` method for new documents and return either a ready-to-use editor instance or loading states.

The component automatically creates debounced snapshots (configurable via `snapshotDebounceMs`) to optimize performance for new clients joining a document. It includes built-in warnings for unsynced changes when closing tabs and supports server-side document transformations through the `transform()` method, which accepts ProseMirror Transform objects for programmatic document modifications.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Collaborative Text Editor Sync is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40convex-dev%2Fprosemirror-sync)
- [GitHub repository](https://github.com/get-convex/prosemirror-sync)
- [Convex Components Directory](https://www.convex.dev/components/prosemirror-sync)
- [Convex documentation](https://docs.convex.dev)