@hocuspocus/server

The collaborative editing backend for Tiptap. Built on Y.js, runs on Node.js (22+), Bun, Deno, and Cloudflare Workers.

Installation

npm install @hocuspocus/server

Usage

Minimal WebSocket server on port 1234:

import { Server } from "@hocuspocus/server"

const server = new Server({
  port: 1234,
})

server.listen()

Hook into the document lifecycle:

import { Server } from "@hocuspocus/server"

const server = new Server({
  port: 1234,

  async onAuthenticate({ token }) {
    if (token !== "super-secret-token") {
      throw new Error("Not authorized!")
    }
  },

  async onLoadDocument({ documentName }) {
    // return a Y.Doc for new documents, or nothing to use the default empty doc
  },

  async onStoreDocument({ documentName, document }) {
    // persist the Y.Doc binary state wherever you like
  },
})

server.listen()

For a database-backed server, combine with an extension like @hocuspocus/extension-sqlite or @hocuspocus/extension-database.

Non-Node.js runtimes

Use the Hocuspocus class directly to attach to any WebSocketLike instance (Bun, Deno, Cloudflare Workers, Express, etc.):

import { Hocuspocus } from "@hocuspocus/server"

const hocuspocus = new Hocuspocus({ /* config */ })

// pass any WebSocket-like instance + request + optional context:
hocuspocus.handleConnection(ws, request, context)

Documentation

Full reference, hooks, extensions, and scaling guides: tiptap.dev/docs/hocuspocus.

License

MIT — see LICENSE.md.