Real-time

About

Payload Real-time wires a Socket.IO server into a Payload instance and emits events whenever documents are created or updated in configured collections. Each emitted payload includes the operation type, collection slug, and the resulting document, broadcast as a `realtime:{slug}` event so frontends can subscribe per collection. Events can be scoped to rooms through a per-collection `room` resolver function. The function receives the resulting document, the operation (`create` or `update`), and the previous document, and returns a room string such as `user:{userId}` or `chat:{id}`. When no room is returned the event broadcasts to all connected clients. You can also restrict which operations trigger events per collection. The plugin starts a standalone Socket.IO server (default port 3001) during Payload's `onInit`, attaches the instance to `payload.io`, and registers the `afterChange` hooks that perform the broadcasts. Because the server instance is exposed on `payload.io`, any custom hook or endpoint can emit arbitrary events to specific rooms for use cases like chat or typing indicators. A React `useRealtime` hook and a standalone `PayloadRealtimeClient` class handle connection lifecycle, room join and leave, presence tracking via `identify`, and subscription to collection or custom events. JWT authentication for socket connections is optional, enabled by setting `requireAuth: true`; the plugin validates the token through Payload's own auth. Note that Socket.IO runs as a separate process-bound server rather than sharing the Next.js HTTP server, and on some setups you need to install the optional `bufferutil` package to resolve a native module error.

Package info

Package name

@alejotoro-o/payload-real-time

Latest version

1.2.0

Unpacked size

47 kB

License

MIT

Weekly downloads

45

Last publish

Dec 31, 2025