No iOS/Android linking required. better-sqlite3 requires a native build; ensure node-gyp prerequisites (Python, C++ compiler) are present on the build machine.

Project setup

1. Copy the source/ directory into your project root, e.g. src/hocuspocus/.
2. If you are importing directly from source (not published packages), add path aliases in tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@hocuspocus/server": ["src/hocuspocus/server/src"],
      "@hocuspocus/common": ["src/hocuspocus/common/src"],
      "@hocuspocus/extension-sqlite": ["src/hocuspocus/extension-sqlite/src"],
      "@hocuspocus/extension-logger": ["src/hocuspocus/extension-logger/src"],
      "@hocuspocus/extension-redis": ["src/hocuspocus/extension-redis/src"],
      "@hocuspocus/extension-s3": ["src/hocuspocus/extension-s3/src"],
      "@hocuspocus/extension-webhook": ["src/hocuspocus/extension-webhook/src"],
      "@hocuspocus/extension-throttle": ["src/hocuspocus/extension-throttle/src"],
      "@hocuspocus/provider": ["src/hocuspocus/provider/src"]
    }
  }
}

3. Set required environment variables for S3 (if used):

AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
AWS_REGION=us-east-1

4. For Redis, pass the ioredis connection options directly to the Redis extension constructor.
5. The server entry point is @hocuspocus/server → Server. Call server.listen() to start.

Public API

Server

import { Server } from '@hocuspocus/server'

const server = new Server({
  port: number,
  extensions: Extension[],
  onConnect?: (data: onConnectPayload) => Promise<any> | any,
  onAuthenticate?: (data: onAuthenticatePayload) => Promise<any> | any,
  onLoadDocument?: (data: onLoadDocumentPayload) => Promise<any> | any,
  onStoreDocument?: (data: onStoreDocumentPayload) => Promise<any> | any,
  onDisconnect?: (data: onDisconnectPayload) => Promise<any> | any,
})

server.listen(): void
server.destroy(): Promise<void>

The central WebSocket orchestrator. Pass hook callbacks and extension instances. Call listen() to bind the port and begin accepting connections.

Logger

import { Logger } from '@hocuspocus/extension-logger'

new Logger({
  log?: (message: string) => void,  // defaults to console.log
})

Drop into the extensions array to receive structured log output for every connection, authentication, and document lifecycle event. Accepts a custom log function to redirect output to your preferred logger (winston, pino, etc.).

SQLite

import { SQLite } from '@hocuspocus/extension-sqlite'

new SQLite({
  database?: string,  // file path or ':memory:', defaults to ':memory:'
})

Persists Y.js document state to a SQLite file using better-sqlite3. Use :memory: for ephemeral development sessions and a file path for durable single-node deployments.

Redis

import { Redis } from '@hocuspocus/extension-redis'

new Redis({
  host: string,
  port: number,
  // any ioredis options
})

Enables horizontal scaling across multiple Hocuspocus server instances via Redis pub/sub. All nodes share document state without direct inter-process connections.

Webhook

import { Webhook } from '@hocuspocus/extension-webhook'

new Webhook({
  url: string,
  secret?: string,
  events?: string[],
})

POSTs JSON payloads to the configured URL on document lifecycle events (connect, disconnect, change, store). Use the secret to verify HMAC signatures on your HTTP endpoint.

Working examples

Scenario - Minimal development server with SQLite

A quick local server persisting documents to disk. Suitable for a single developer or staging environment.

import { Server } from '@hocuspocus/server'
import { Logger } from '@hocuspocus/extension-logger'
import { SQLite } from '@hocuspocus/extension-sqlite'

const server = new Server({
  port: 1234,

  async onConnect({ requestParameters }) {
    console.log('Client connected', requestParameters.get('room'))
  },

  extensions: [
    new Logger(),
    new SQLite({ database: './collab.sqlite' }),
  ],
})

server.listen()

Scenario - Production server with Redis scaling and S3 storage

Multi-node deployment with Redis for cross-instance sync and S3 for durable document storage.

import { Server } from '@hocuspocus/server'
import { Logger } from '@hocuspocus/extension-logger'
import { Redis } from '@hocuspocus/extension-redis'
import { S3 } from '@hocuspocus/extension-s3'

const server = new Server({
  port: Number(process.env.PORT) || 1234,

  async onAuthenticate({ token }) {
    if (token !== process.env.AUTH_TOKEN) {
      throw new Error('Unauthorized')
    }
  },

  extensions: [
    new Logger(),
    new Redis({
      host: process.env.REDIS_HOST ?? '127.0.0.1',
      port: 6379,
    }),
    new S3({
      bucket: process.env.S3_BUCKET!,
      region: process.env.AWS_REGION ?? 'us-east-1',
    }),
  ],
})

server.listen()

Scenario - Outbound webhooks for document change notifications

Notify an external API whenever a document is stored, using the Webhook extension with HMAC signing.

import { Server } from '@hocuspocus/server'
import { SQLite } from '@hocuspocus/extension-sqlite'
import { Webhook } from '@hocuspocus/extension-webhook'

const server = new Server({
  port: 1234,
  extensions: [
    new SQLite({ database: ':memory:' }),
    new Webhook({
      url: 'https://api.example.com/hocuspocus/events',
      secret: process.env.WEBHOOK_SECRET,
    }),
  ],
})

server.listen()

// Graceful shutdown
process.on('SIGTERM', async () => {
  await server.destroy()
  process.exit(0)
})

File walkthrough

• cli/ - Meow-based CLI binary; parses --port, --sqlite, --s3, --webhook flags and boots a Server instance with the appropriate extensions.
• common/ - Exports shared types (types.ts), auth helpers (auth.ts), close-event constants (CloseEvents.ts), awareness array conversion (awarenessStatesToArray.ts), routing key utils (routingKey.ts), and SkipFurtherHooksError.
• extension-database/ - Abstract Database extension; subclass it to implement fetchPayload and storePayload for any custom data store.
• extension-logger/ - Logger class that hooks into all server lifecycle events and emits formatted log lines.
• extension-redis/ - Redis extension using ioredis pub/sub to broadcast document updates across server replicas.
• extension-s3/ - S3 extension wrapping the AWS SDK to load and persist Y.js binary document states as S3 objects.
• extension-sqlite/ - SQLite extension using better-sqlite3 for synchronous local file persistence.
• extension-throttle/ - Throttle extension enforcing connection and message rate limits per client.
• extension-webhook/ - Webhook extension that serializes lifecycle payloads and POSTs them with optional HMAC signatures.
• provider/ - Client-side HocuspocusProvider and HocuspocusProviderWebsocket; manages WebSocket connection, reconnection, awareness, and Y.js sync protocol.
• provider-react/ - React hooks (e.g., useHocuspocus) wrapping the provider for component-level usage.
• server/ - Core Server class: WebSocket upgrade handling, document management, extension pipeline, and hook orchestration.
• transformer/ - Utilities to convert Y.js document state to/from Tiptap JSON or ProseMirror documents.

Common pitfalls and fixes

• better-sqlite3 build failure on CI: install python3, make, and g++ before npm install; on Alpine Linux add apk add python3 make g++.
• ESM/CJS interop: Hocuspocus packages are ESM; ensure "type": "module" in your package.json or use a bundler (esbuild, Vite) with ESM output.
• AWS_REGION not picked up by S3 extension: always pass region explicitly in the S3 constructor rather than relying solely on the environment variable.
• Redis pub/sub messages not routing: all server instances must share the same Redis host and use identical routingKey configuration; mismatched keys silently drop updates.
• Authentication hook throwing does not close connection cleanly: throw an Error instance (not a string) inside onAuthenticate; the server maps the error message to the WebSocket close reason.
• SkipFurtherHooksError misuse: import it from @hocuspocus/common, not from @hocuspocus/server; throwing it inside a hook short-circuits the remaining extension chain without treating it as an error.

Vibe-coding prompt template

I have the Hocuspocus source code in `source/` and its integration guide in `USAGE.md`.
The upstream package is `hocuspocus` (packages: @hocuspocus/server, @hocuspocus/common,
@hocuspocus/extension-sqlite, @hocuspocus/extension-logger, @hocuspocus/extension-redis,
@hocuspocus/extension-s3, @hocuspocus/extension-webhook, @hocuspocus/provider).

Please integrate Hocuspocus into my existing Node.js/TypeScript project step by step:

1. Read `USAGE.md` fully before writing any code.
2. Install the required dependencies listed in the "Required dependencies" section.
3. Create a `src/collab-server.ts` file that boots a `Server` with the Logger and SQLite
   extensions, listening on port 1234.
4. Wire the server startup into my existing Express app so it shares the HTTP server
   (or starts independently if that is simpler).
5. Add an `onAuthenticate` hook that validates a Bearer token from the WebSocket
   handshake headers using my existing auth middleware.
6. If I ask for Redis scaling, add the Redis extension using `REDIS_HOST` and
   `REDIS_PORT` environment variables.
7. Show me where to add the client-side `HocuspocusProvider` in my frontend, importing
   from `@hocuspocus/provider`.
8. Do not invent any APIs; use only the exports documented in `USAGE.md` and visible
   in `source/`.

License and credit

Hocuspocus is released under the MIT License. See source/LICENSE.md if present in your copy, or refer to the upstream repository. The upstream npm packages are published under the @hocuspocus scope by ueberdosis / Tiptap.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

PartyKit Real-Time Multiplayer Backend Platform

Automation, Utilities & Developer Tools

Free