@hocuspocus/extension-redis

Scale Hocuspocus horizontally across multiple server instances. Uses Redis pub/sub to broadcast document updates and awareness between servers, so clients connected to different instances stay in sync on the same document.

Installation

npm install @hocuspocus/extension-redis

Usage

Point every Hocuspocus instance at the same Redis:

import { Server } from "@hocuspocus/server"
import { Redis } from "@hocuspocus/extension-redis"

const server = new Server({
  port: 1234,
  extensions: [
    new Redis({
      host: "127.0.0.1",
      port: 6379,
    }),
  ],
})

server.listen()

Bring your own Redis client

If you already have an ioredis client (including Cluster), pass it in directly instead of host/port:

import RedisClient from "ioredis"

new Redis({
  redis: new RedisClient({ host: "127.0.0.1", port: 6379 }),
})

Redis handles real-time sync — you still need a persistence extension (e.g. @hocuspocus/extension-sqlite, @hocuspocus/extension-s3, or your own Database) to store documents long-term.

Consistent reads on load

When a document is loaded on one instance while another instance already has it open (and possibly modified in memory, not yet persisted), the load blocks until the other instance has sent its current state — so a DirectConnection or a freshly connected client observes the latest collaborative content rather than just what was read from storage. If no other instance has the document open, the load is not delayed.

The wait is bounded by awaitInitialSyncTimeout (ms, default 1000). Set it to 0 to disable the wait and restore the previous fire-and-forget behavior:

new Redis({
  host: "127.0.0.1",
  port: 6379,
  awaitInitialSyncTimeout: 1000,
})

Documentation

Full scaling architecture and multi-instance deployment guide: tiptap.dev/docs/hocuspocus/server/extensions/redis.

License

MIT — see LICENSE.md.