Self-Hosted Collaboration

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

SuperDoc’s integration contract is provider-agnostic: pass { ydoc, provider } to modules.collaboration and the server choice is yours. Any Yjs-compatible server works.

Option	Notes	Setup Time
YHub	Advanced Yjs backend for attribution, activity, and revision-history workflows. Beta; validate licensing and infrastructure requirements.	1+ hour
Hocuspocus	Mature self-hosted Yjs server with auth, persistence, and scaling hooks.	30 mins
SuperDoc Yjs	Minimal reference server for prototypes and local development. Not production infrastructure.	30 mins

At a glance

YHub

Advanced Yjs backend for attribution, activity, and revision-history workflows. Redis + Postgres backing. Beta; validate licensing and infrastructure requirements.

Setup guide

Hocuspocus

Mature self-hosted Yjs server with auth, persistence, and scaling hooks.

npm install @hocuspocus/server @hocuspocus/provider

Setup guide

SuperDoc Yjs

A small Yjs WebSocket server we ship for prototypes and local development. Not production infrastructure: no built-in auth, persistence, scaling, or observability.

npm install @superdoc-dev/superdoc-yjs-collaboration

Reference

Client connection options

The supported contract is provider-agnostic: you create the Yjs provider, SuperDoc plugs into it.

Provider-agnostic (recommended)

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 }
  }
});

This shape works with any Yjs provider: HocuspocusProvider, WebsocketProvider from y-websocket (compatible with YHub and SuperDoc Yjs), LiveblocksYjsProvider, or your own.

URL-based (deprecated)

This path is deprecated. SuperDoc creates the provider internally and emits a console warning. Use the provider-agnostic shape above for new code.

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

Requirements

Server

• Node.js 18+
• WebSocket support (native or via library)
• Persistent storage for Yjs updates or snapshots
• Optional object storage for DOCX exports and archive snapshots

Network

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

Next steps

YHub setup

Attribution and revision-history workflows (beta)

Hocuspocus setup

Mature self-hosted Yjs server

SuperDoc Yjs reference

Minimal server for prototypes and local development

Configuration

All client-side options and events