snapshot of https://github.com/ueberdosis/hocuspocus.git @ cf3cfa355b4d3bb61c6b6c80071f71783e32470e (2026-09-15)

packages/server/README.md

@@ -0,0 +1,107 @@
+# @hocuspocus/server
+[![Version](https://img.shields.io/npm/v/@hocuspocus/server.svg?label=version)](https://www.npmjs.com/package/@hocuspocus/server)
+[![Downloads](https://img.shields.io/npm/dm/@hocuspocus/server.svg)](https://npmcharts.com/compare/tiptap?minimal=true)
+[![License](https://img.shields.io/npm/l/@hocuspocus/server.svg)](https://www.npmjs.com/package/@hocuspocus/server)
+[![Sponsor](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/ueberdosis)
+
+The collaborative editing backend for [Tiptap](https://github.com/ueberdosis/tiptap). Built on [Y.js](https://github.com/yjs/yjs), 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 →](https://docs.google.com/forms/d/e/1FAIpQLSeUS8S1iZTud58GBSD_d4c8lfUvkZHvzU99kWxP1wnNZnPKpw/viewform?usp=header)**
+
+## Installation
+
+```bash
+npm install @hocuspocus/server
+```
+
+## Usage
+
+Minimal WebSocket server on port `1234`:
+
+```js
+import { Server } from "@hocuspocus/server"
+
+const server = new Server({
+  port: 1234,
+})
+
+server.listen()
+```
+
+Hook into the document lifecycle:
+
+```js
+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`](../extension-sqlite) or [`@hocuspocus/extension-database`](../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.
+
+```js
+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.):
+
+```js
+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](https://tiptap.dev/docs/hocuspocus).
+
+## License
+
+MIT — see [LICENSE.md](https://github.com/ueberdosis/hocuspocus/blob/main/LICENSE.md).