e0c588ca1c
Some checks failed
build / lint (22) (push) Failing after 17s
build / test (22) (push) Failing after 8s
build / lint (23) (push) Failing after 2s
build / build (22) (push) Has been skipped
build / build (23) (push) Has been skipped
build / test (23) (push) Failing after 4s
docsearch / docsearch (push) Failing after 1s
108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# @hocuspocus/server
|
||
[](https://www.npmjs.com/package/@hocuspocus/server)
|
||
[](https://npmcharts.com/compare/tiptap?minimal=true)
|
||
[](https://www.npmjs.com/package/@hocuspocus/server)
|
||
[](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).
|