Skip to main content
Run your own collaboration infrastructure for full control over data, persistence, and scaling.

​
Why Self-Host?

Data Control

Keep all data on your infrastructure

Custom Persistence

Use your own database (PostgreSQL, S3, Redis)

On-Premise

Deploy behind your firewall

No Vendor Lock-in

Standard Yjs protocol, portable data

​
Architecture

​
Choose Your Approach

OptionBest ForSetup Time
SuperDoc YjsNew projects, recommended30 mins
HocuspocusTipTap ecosystem users30 mins
Y-SweetHigh performance, easy deployment30 mins

​
Quick Comparison

  • SuperDoc Yjs
  • Hocuspocus
  • Y-Sweet
Our official collaboration package
  • Purpose-built for SuperDoc
  • Builder pattern API
  • Auto-save with debounce
  • Memory management
npm install @superdoc-dev/superdoc-yjs-collaboration
Get Started

​
Client Connection Options

When self-hosting, you have two ways to connect SuperDoc:

​
Option 1: URL-based (SuperDoc manages provider)

SuperDoc creates and manages the WebSocket connection: 
new SuperDoc({
  selector: '#editor',
  modules: {
    collaboration: {
      url: 'wss://your-server.com/doc',
      token: 'auth-token'
    }
  }
});

​
Option 2: Provider-agnostic (You manage provider)

You create the Yjs provider yourself: 
import { HocuspocusProvider } from '@hocuspocus/provider';
import * as Y from 'yjs';

const ydoc = new Y.Doc();
const provider = new HocuspocusProvider({
  url: 'wss://your-server.com',
  name: 'document-123',
  document: ydoc
});

new SuperDoc({
  selector: '#editor',
  modules: {
    collaboration: { ydoc, provider }
  }
});
The provider-agnostic approach gives you more control but requires managing the provider lifecycle yourself.

​
Requirements

​
Server

  • Node.js 18+
  • WebSocket support (native or via library)
  • Persistent storage for documents

​
Network

  • WSS (WebSocket Secure) in production
  • Proper CORS configuration
  • Load balancer with sticky sessions (if scaling)

​
Next Steps

SuperDoc Yjs

Recommended - our official package

Hocuspocus

Alternative using TipTap’s server

Y-Sweet

High performance Rust-based server

Configuration

All client-side options and events