Hocuspocus: Backend Cộng Tác Yjs
Hocuspocus là một backend WebSocket đồng bộ document Yjs CRDT giữa các client, giúp nhiều người cùng chỉnh sửa một tài liệu mà không xung đột merge. Nó chạy như một server plug & play bạn tự vận hành, có sẵn extension SQLite theo ví dụ README, cùng Tiptap Collab làm phương án hosted dự phòng. Dùng nếu bạn đã xây trên Yjs và muốn server tự kiểm soát; bỏ qua nếu cần một API cộng tác hosted dùng ngay thay vì một tiến trình Node phải tự vận hành.
Hocuspocus là gì?
Hocuspocus là một backend WebSocket mã nguồn mở, viết bằng TypeScript, kết nối các document Yjs CRDT giữa các client để chỉnh sửa hợp nhất mà không xung đột, theo thời gian thực. Nó nằm giữa editor ở frontend và lớp lưu trữ bạn gắn vào qua hệ thống extension, chẳng hạn extension SQLite có sẵn trong README. GitHub topic của repo gắn thẻ nó với prosemirror, slatejs, tiptap, yjs và crdt, và nó dùng giấy phép MIT.
Đơn giản hoá việc cộng tác thời gian thực
Yjs cho bạn một CRDT để hợp nhất các chỉnh sửa tài liệu, nhưng nó không đi kèm server — bạn vẫn phải tự viết phần xử lý WebSocket, lưu trữ, và vòng đời kết nối để đồng bộ document Yjs giữa các client. Hocuspocus chính là mảnh còn thiếu đó: một backend được xây dựng riêng quanh Y.js, xử lý lớp WebSocket và cung cấp các hook như onConnect, để bạn không phải viết lại một server đồng bộ từ đầu mỗi khi thêm tính năng cộng tác vào một ứng dụng.
Tính năng và khả năng cốt lõi
- ✓Một server WebSocket được xây riêng cho Yjs — README mô tả nó như một collaboration server sẵn sàng chạy ngay, thay vì một bộ công cụ bạn phải tự lắp ráp.
- ✓Hệ thống extension để lưu trữ: ví dụ sử dụng trong README gắn package @hocuspocus/extension-sqlite để ghi document vào file db.sqlite.
- ✓Các hook vòng đời như onConnect chạy code của riêng bạn khi một client kết nối — logging, kiểm tra auth, hoặc bất cứ gì bạn cần ở lớp WebSocket.
- ✓Mặc định lắng nghe tại http://127.0.0.1 (ws:// cho giao thức WebSocket), với port được đặt trong constructor của Server — là 1234 trong ví dụ của README.
- ✓Được gắn thẻ self-hosted trên GitHub, với Tiptap Collab là lựa chọn hosted chính thức nếu bạn không muốn tự chạy server.
- ✓Phiên bản đầu tiên do kris viết, với đóng góp được ghi nhận từ Tom Moor và YousefED của TypeCellOS trong phần Contributors của README.
Thiết lập một Hocuspocus Server
Ví dụ trong README khởi tạo một server bằng class Server import từ @hocuspocus/server, lắng nghe ở port 1234. Bạn đăng ký các extension trong một mảng — ví dụ dùng extension SQLite trỏ tới file db.sqlite, nên document được lưu vào file cục bộ mà bạn không phải tự viết code lưu trữ. Một hook onConnect bất đồng bộ (async) chạy khi một client kết nối, đây là nơi bạn thêm logic như kiểm tra auth trước khi Hocuspocus hoàn tất kết nối. Gọi .listen() là server đã chạy; trỏ WebSocket provider của một editor hỗ trợ Yjs vào đó và các chỉnh sửa bắt đầu đồng bộ.
Điểm mạnh
- ✓Được xây riêng cho Yjs thay vì một lớp pub/sub chung chung — phần xử lý WebSocket và đồng bộ CRDT đã được ghép sẵn với nhau, theo đúng mô tả của README.
- ✓Ví dụ trong README là một server chạy được thật với phần lưu trữ đi kèm, không chỉ là tài liệu tham khảo API.
- ✓Tự chạy server nghĩa là document không cần rời khỏi hạ tầng của riêng bạn — Tiptap Collab tồn tại như một phương án dự phòng nếu sau này bạn muốn giao lại việc đó.
- ✓Cấp phép MIT, nên không có rào cản giấy phép khi dùng cho mục đích thương mại.
- ✓Có các sponsor được nêu tên — gồm Cargo, Saga, Gamma, Outline, Ahrefs, Brickdoc, Sana, và Poggio, theo phần Sponsors của README — cùng đội Tiptap vẫn đang hoạt động phía sau.
Những điều cần cân nhắc khi triển khai
- △README không ghi rõ lệnh cài đặt — bạn phải tự suy ra tên package từ các dòng import trong ví dụ sử dụng, chứ không có mục cài đặt riêng.
- △Tài liệu đầy đủ nằm ngoài repo, trên trang docs của Tiptap, nên bất cứ điều gì ngoài README này và ví dụ sử dụng duy nhất của nó đều không thể kiểm chứng từ các dữ kiện có ở đây.
- △Ví dụ có sẵn chỉ minh hoạ lưu trữ bằng SQLite; README không nói rõ những storage backend nào khác được cung cấp dưới dạng extension.
- △README không có số phiên bản hay changelog, nên không có cơ sở tài liệu nào để biết nhịp độ phát hành chỉ dựa trên các dữ kiện của repo.
- △Auth, khả năng mở rộng (scaling), và việc làm cứng cho production không được đề cập trong README — hook vòng đời duy nhất được nêu là onConnect, còn lại đều được đẩy sang tài liệu riêng của Tiptap.
Cloud Hosting và các lựa chọn khác
Câu hỏi thường gặp
Hocuspocus được phát hành theo MIT License, theo file LICENSE.md và mục license trên GitHub của repository.
Hocuspocus đồng bộ document bằng Y.js, một CRDT, nên các chỉnh sửa từ nhiều client tự động hợp nhất mà không xung đột. README mô tả chính Hocuspocus là backend WebSocket được xây dựng riêng quanh CRDT đó.
Hocuspocus có thể tự host — nó được gắn thẻ self-hosted trên GitHub, và ví dụ sử dụng trong README chạy server qua class Server từ @hocuspocus/server, không phải một dịch vụ được quản lý sẵn.
README của Hocuspocus trỏ tới Tiptap Collab như lựa chọn cloud-hosted chính thức, dành cho những đội muốn dùng Hocuspocus mà không phải tự vận hành WebSocket server.
README không liệt kê các editor tương thích bằng văn xuôi, nhưng GitHub topic của chính repo gắn thẻ nó với prosemirror, slatejs, và tiptap bên cạnh yjs, vì Hocuspocus đồng bộ với bất kỳ editor nào tạo ra document Yjs ở phía client.
README của Hocuspocus hướng câu hỏi và phản hồi tới [email protected], một GitHub issue, hoặc server Discord của Tiptap, được liên kết trực tiếp để thảo luận cộng đồng.
Trường hợp sử dụng tốt nhất
- •Thêm tính năng cùng chỉnh sửa (co-editing) trực tiếp cho một trình soạn thảo rich text dựa trên Tiptap mà không phải tự viết một WebSocket sync server.
- •Thiết lập chỉnh sửa đa người dùng không xung đột cho một editor dựa trên ProseMirror hoặc Slate.js, vì chính GitHub topic của repo gắn thẻ cho cả hai.
- •Thử nghiệm cộng tác thời gian thực cục bộ với extension SQLite có sẵn trước khi chuyển sang một database lớn hơn.
- •Tự host một collaboration backend thay vì để document đi qua server của một API bên thứ ba.
Cách cài đặt / dùng thử
README không có lệnh cài đặt rõ ràng — không có dòng npm install, yarn add, hay pnpm add nào xuất hiện trong đó. Điều bạn có thể suy ra từ ví dụ sử dụng: server được phân phối dưới dạng package @hocuspocus/server, còn các extension lưu trữ như @hocuspocus/extension-sqlite là các package riêng bạn thêm khi cần. Với quy trình thiết lập đầy đủ, README trỏ tới tài liệu tại hocuspocus.dev/introduction thay vì trình bày trực tiếp việc cài đặt ở đây.
Ai nên dùng — và ai nên bỏ qua
Hãy thử Hocuspocus nếu bạn đã xây dựng trên Yjs — nhất là với Tiptap, ProseMirror, hoặc Slate.js — và muốn một WebSocket server do chính bạn chạy và sở hữu thay vì tự lắp ráp từ các thành phần cấp thấp hơn của Yjs. Bỏ qua nếu bạn không muốn vận hành một server Node chút nào: Tiptap Collab — chính là lựa chọn hosted của README — hoặc một API cộng tác được quản lý hoàn toàn bởi bên thứ ba sẽ loại bỏ hẳn phần vận hành đó.
Repo liên quan
Vẫn đang phân vân về hocuspocus?
Một cú bấm sẽ gửi câu hỏi kèm trang này cho AI — xem AI nói gì về hocuspocus.
