One Server object, seven playground backends, and a default port nobody states
The Yjs CRDT WebSocket backend for conflict-free real-time collaboration in your app.
At a glance
- What is it?
- Hocuspocus is a Y.js collaboration backend you wire up in about ten lines, with an extensions array as the seam for storage and adapters; what the page does not tell you is the default port, and what the repository tells you instead is seven playground entry points, an ava setup that forces the test process to exit, and four overlapping build and lint configurations.
- Who is it for?
- Hocuspocus fits a team already using Yjs and Tiptap that wants the server to be a few lines rather than a service to own. Before you build on it, read the two things the front page leaves open.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 4 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- ueberdosis/hocuspocus2,654 ★ · +78
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| ueberdosis/hocuspocus | 2.6k | 2.7k |
78 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
One Server object and an extensions array
The entire example is short enough to read in one pass, and it is the whole public surface the page offers:
import { Server } from '@hocuspocus/server'
import { SQLite } from '@hocuspocus/extension-sqlite'
const server = new Server({
port: 1234,
async onConnect() {
console.log('🔮')
},
extensions: [
new SQLite({
database: 'db.sqlite',
}),
],
});
server.listen();A `Server` from `@hocuspocus/server` takes configuration, an extensions array carries storage and adapter behaviour, and `server.listen()` starts accepting connections. The project describes itself as a plug and play collaboration backend built on Y.js, so the CRDT logic is not yours to write; what you are choosing is the extensions. The single example picks SQLite pointed at `db.sqlite`, which tells you the shape of every other storage option without naming a single one of them.
The default host is stated and the default port is not
One sentence describes the default: the server listens on `http://127.0.0.1`, or prefixed with the WebSocket protocol on `ws://127.0.0.1`. That sentence names a host and deliberately does not name a port, and the code right below it sets `port: 1234`, so a reader who copies the sentence instead of the code gets the loopback binding right and still has to choose a port. Loopback by default also means the collaboration server is not reachable from another machine out of the box, which is the right default and worth knowing before you deploy it behind nothing. Two smaller tells sit in the same block: the `onConnect` hook is present and its body is a single log line, so the hook's contract is demonstrated by its existence rather than by its return value, and the sentence introducing the example describes it as an example setup in slightly broken grammar.
Seven playground backends stand in for the adapter documentation
The compatibility surface is demonstrated rather than described. The root scripts start a playground with a frontend dev server and exactly one backend entry point, seven variants of it: the default, an express one, a koa one, a redis one, a webhook one, one called slow, and one that loads a document. Each is a `concurrently` invocation that starts both halves and kills the others when one exits. Read as a matrix, they tell you the project expects to be embedded in an existing HTTP server as easily as run on its own, that Redis is a supported piece of infrastructure, and that webhook handling and slow connections are scenarios somebody cared to keep working. The only compose file in the repository matches that list exactly: one service, an image of redis on the alpine variant, with its port published.
A test suite that force-exits and leans on experimental Node flags
The ava block in the root manifest is the most opinionated configuration in the repository. It points at `tests/**/*` and excludes both `tests/utils` and a `database` directory, then requires a helper named `_force-exit.ts`, which is an admission that the suite would otherwise hang and is being told to leave rather than being fixed. Worker threads are switched off, the timeout is thirty seconds, and the run passes four Node arguments: no warnings, a source condition, and two experimental flags for transforming types and for specifier resolution. That is a suite running TypeScript straight through experimental transforms rather than compiling first. The practical consequence for a contributor is that the test command's behaviour depends on Node flags the project chose to pin, so a Node upgrade is a change to this file as much as to the code.
Two bundlers and two linters configured at the same root
The build tooling overlaps in ways that cost time to work out. There is a `babel.config.cjs` and a `rolldown.config.js`, so two bundler configurations exist; a `biome.json` and an `.eslintignore`, so two linting setups are referenced, and no eslint configuration file appears at the root to go with that ignore file. Package management is pnpm with workspaces, a `pnpm-workspace.yaml`, a lockfile, and `lerna.json` still in the tree, and the manifest pins a specific pnpm release with a hash rather than a range. The manifest is marked private and declares the module type as ESM, and the browser target list is defaults, not IE 11, and maintained node versions, which is a deliberate statement about who the output is for.
The front page opens with a survey and a gift card
The first thing on the page is a callout asking readers to help chart the future of the project in a short survey, with a chance to earn a fifty dollar gift card as the incentive, and the link is a Google form rather than anything hosted here. After that, the page is mostly navigation: documentation at the official docs site, a cloud offering called Tiptap Collab for people who would rather not host it, a Discord for community questions, an email address for feedback, and a contributors section that credits kris with the initial version alongside Tom Moor, YousefED, and many more. The sponsor table lists nine named companies and then thanks hundreds of others in a line with a spelling error, which is a fair signal of how little editing that section gets.
Two changelogs, a security policy, and a monthly minor release
Change information is duplicated at the root: a `CHANGELOG.md` and a `RELEASE_NOTES_V4.md` that is specific to the current major, so a reader looking for what changed in 4.x has a second place to look and has to know which one is authoritative. `SECURITY.md` sits beside them, and the licence is MIT with the text in `LICENSE.md`, which is the file the README points at. Releases move on a minor version every few weeks: v4.5.0 on 2026-08-04, v4.6.0 on 2026-08-10, v4.7.0 on 2026-09-09, with the last recorded push on 2026-10-02. Two smaller root files say something about how the project works: a CodeRabbit configuration and a DocSearch configuration for the documentation site.
Editorial conclusion
Hocuspocus fits a team already using Yjs and Tiptap that wants the server to be a few lines rather than a service to own. Before you build on it, read the two things the front page leaves open. The default listen port is never stated, only the default host, so set one explicitly rather than assuming. And the extension list is where your data model lives, so pick that before anything else: the example persists to a single SQLite file, which is fine for one process and is not a multi-node story. The package is MIT with the licence text and a security policy in the root, the release cadence is a minor version every few weeks, and the documentation, including the extension reference, lives off this repository.
Frequently asked questions
What is Hocuspocus and how do I start it?
It is a Y.js collaboration backend published as the `@hocuspocus/server` package. You construct a `Server` with configuration and an extensions array, then call `server.listen()`. The example passes `port: 1234`.
How does Hocuspocus persist documents?
Through extensions. The example wires `@hocuspocus/extension-sqlite` with `database: 'db.sqlite'`, and the repository ships playground entry points for express, koa, redis, webhook, a slow variant, and a document loader.
What host and port does Hocuspocus listen on?
The page states the default as `http://127.0.0.1`, or `ws://127.0.0.1` with the WebSocket prefix, and does not name a default port anywhere. The example sets port 1234 explicitly.
Is there a hosted version of Hocuspocus?
Yes, a cloud offering named Tiptap Collab, linked from the README, for people who want the backend without hosting it. Community questions go to the Tiptap Discord and feedback to the [email protected] address.
What license is Hocuspocus released under?
MIT, with the licence text in `LICENSE.md` at the root of the repository, next to a `SECURITY.md`.
How do the Hocuspocus tests run?
Through ava, configured in the root manifest. It points at `tests/**/*`, excludes `tests/utils` and `database`, requires a helper that forces the process to exit, turns worker threads off, applies experimental Node flags for TypeScript transforms, and uses a thirty second timeout.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/ueberdosis-hocuspocus)Star history chart for your README
[](https://hysenlabs.com/projects/ueberdosis-hocuspocus)Was this useful?