upstream-hocuspocus/packages/server

@hocuspocus/server

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

Tip

Help us chart the future of Hocuspocus by telling us about your needs in a short survey. Plus, you’ll get a chance to earn a $50 gift card. Take the survey →

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.

Resource limits

Messages received from a client before authentication completes are buffered in memory. To prevent an unauthenticated client from exhausting server memory, the server bounds this buffer per connection and closes connections that exceed the limits. The defaults are safe for typical clients (which authenticate before sending document data); raise them only if you have a specific need.

const server = new Server({
  port: 1234,

  // Max bytes buffered across all documents of one unauthenticated connection.
  maxUnauthenticatedQueueSize: 5 * 1024 * 1024, // default: 5 MiB

  // Max number of messages buffered for one unauthenticated connection.
  maxUnauthenticatedQueueMessages: 1_000, // default: 1000

  // Max number of documents one connection may open before authenticating any.
  maxPendingDocuments: 100, // default: 100

  // Connections that don't authenticate any document within `timeout` ms are
  // closed. This deadline is not refreshed by inbound traffic.
  timeout: 60_000, // default: 60s
})

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.