Skip to content

IO class (strapi.$io) ​

The plugin creates one SocketIO instance during bootstrap and exposes it as strapi.$io. Use it from services, controllers, lifecycles or cron jobs.

Quick reference ​

js
await strapi.$io.emit({ event, schema, data }); // content event, sanitized per audience
await strapi.$io.emitIdentifier({ event, schema, data: { documentId, locale } });
await strapi.$io.raw({ event, data, rooms }); // custom event, sensitive keys removed

await strapi.$io.joinRoom(socketId, room); // false for plugin rooms
await strapi.$io.leaveRoom(socketId, room);
await strapi.$io.getSocketsInRoom(room); // socket ids
strapi.$io.sendPrivateMessage(socketId, event, data);
strapi.$io.broadcast(socketId, event, data); // everyone except socketId
strapi.$io.emitToNamespace('chat', event, data);
await strapi.$io.disconnectSocket(socketId);
await strapi.$io.revalidateSockets(kinds?, { ids? });
await strapi.$io.subscribeToEntity(socketId, uid, documentId); // same checks as subscribe-entity
strapi.$io.unsubscribeFromEntity(socketId, uid, documentId);
strapi.$io.getEntitySubscriptions(socketId);

strapi.$io.server; // Socket.IO Server
strapi.$io.namespaces; // { '': Namespace, chat: Namespace }

emit() ​

Sends a content event to every role and API token that may read the content type (find or findOne). Each audience receives the entry sanitized with its own permissions. If sanitizing fails for an audience, that audience is skipped.

ts
emit(options: { event: string; schema: string | { uid: string; singularName?: string }; data: object }): Promise<number>
  • The event name is <singularName>:<event>, for example article:update.
  • Returns the number of rooms that received the event. With the default in-memory adapter, rooms without sockets are skipped before sanitizing and not counted.
  • The payload is { data: { id, attributes }, meta: {} }.
js
const entry = await strapi.documents('api::article.article').findOne({ documentId, populate: ['author'] });
await strapi.$io.emit({ event: 'update', schema: 'api::article.article', data: entry });

The plugin calls emit() itself for watched content types, so you only need it for content you do not watch or events you build yourself.

emitIdentifier() ​

Sends { data: { documentId, locale? } } to the audiences that may read the type. The plugin uses it for delete and unpublish.

js
await strapi.$io.emitIdentifier({
  event: 'delete',
  schema: 'api::article.article',
  data: { documentId, locale: 'en' },
});

raw() ​

Sends a custom event as { data }. Keys from the sensitive field list are removed first. Without rooms the event goes to every connected client of the default namespace.

ts
raw(options: { event: string; data: unknown; rooms?: string[] }): Promise<void>
js
await strapi.$io.raw({ event: 'maintenance', data: { startsAt: '22:00 UTC' } });
await strapi.$io.raw({ event: 'report:ready', data: { id }, rooms: [`user-${userId}`] });

raw() does not check permissions. Choose the rooms yourself.

Room helpers ​

MethodReturnsNotes
joinRoom(socketId, room)boolean | Promise<boolean>false when the socket is unknown or the room belongs to the plugin. A Promise for a socket on another process (multi-server adapter).
leaveRoom(socketId, room)boolean | Promise<boolean>false when the socket is unknown.
getSocketsInRoom(room)Promise<string[]>Socket ids, across instances when an adapter such as Redis is attached.
sendPrivateMessage(socketId, event, data)voidSends data as is (no sanitizing).
broadcast(socketId, event, data)voidEveryone except socketId.
emitToNamespace(namespace, event, data)voidnamespace with or without the leading slash.
disconnectSocket(socketId)boolean | Promise<boolean>Closes the connection of that one socket.

Plugin rooms (io-role-, io-token-, io-admin-, io-entity-, presence:) cannot be joined with joinRoom().

The helpers that take a socketId (these three and the entity subscription helpers below) act on exactly one socket. With a multi-server adapter they look the id up across processes (fetchSockets()) and act only on a socket whose id equals it, so a room name such as io-role-authenticated passed as socketId (for example from a client request) returns false and never selects the sockets of that room. For a socket on another process they return a Promise; await the result, which also works for the plain value on one process.

With entity subscriptions, maxPerSocket is a hard cap for every call made on one process, including parallel subscribeToEntity() calls for a socket on another process. Parallel calls for the same socket made on several processes at the same moment are each checked against the rooms the socket had when the call started, so they can exceed the cap by the number of those processes minus one.

revalidateSockets() ​

Re-checks authenticated sockets and disconnects those whose credentials are no longer valid: expired or invalid JWT, blocked user, changed role, revoked Strapi session, deleted or expired API token, deactivated admin, or an admin who lost read access to an entry the presence panel has open.

ts
revalidateSockets(kinds?: Array<'user' | 'token' | 'admin'>, options?: { ids?: Iterable<number | string> }): Promise<number>
js
await strapi.$io.revalidateSockets(); // everything
await strapi.$io.revalidateSockets(['user'], { ids: [userId] }); // one user's sockets

Returns the number of disconnected sockets. Sockets are checked in one batch per kind (one query for all users, one for all tokens, one for all admins). The plugin already runs this every five minutes and right after users, admins, API tokens or Strapi sessions change, so you rarely need to call it.

server and namespaces ​

js
strapi.$io.server.emit('hello', { ok: true }); // the Socket.IO Server, no sanitizing
strapi.$io.server.to('io-role-authenticated').emit('notice', { text: 'Hi' });
Object.keys(strapi.$io.namespaces); // ['', 'chat']

Namespaces created with strapi.$io.server.of('/name') get the plugin handshake. Content events go to the default namespace only.

Monitoring service ​

Counts only, never IP addresses, emails, tokens or socket ids:

js
const monitoring = strapi.plugin('io').service('monitoring');
await monitoring.getConnectionStats(); // { connected, rooms, byKind: { admin, user, token, public } }
monitoring.getEventStats(); // { totalEvents, eventsPerSecond, lastEventAt, totalConnections, since }
monitoring.getEventLog(50); // newest first, when the event log is on

Client payloads ​

js
socket.on('article:update', ({ data }) => render(data.attributes)); // emit()
socket.on('article:delete', ({ data }) => remove(data.documentId)); // emitIdentifier()
socket.on('maintenance', ({ data }) => banner(data.startsAt)); // raw()

TypeScript ​

The package ships types.d.ts and adds $io to Core.Strapi:

ts
import type { SocketIOConfig, SocketData } from '@strapi-community/plugin-io/strapi-server';

const config: SocketIOConfig = { contentTypes: ['api::article.article'] };

const handler = (_ctx: unknown, socket: { data: SocketData }) => {
  if (socket.data.kind === 'user') console.log(socket.data.user?.id);
};

Entity subscriptions ​

Clients can follow single entries once Settings > Socket.IO > Entry subscriptions is on. Each subscription is checked against the read permission of the client's own role or API token, and every event is sanitized with those permissions. Subscribers also receive events of content types and actions that are not broadcast under Events; a client that is in both its role room and an entry room receives each event once.

js
// client
socket.emit('subscribe-entity', { uid: 'api::article.article', documentId }, (reply) => {
  // { success: true, uid, documentId, id } or { success: false, error }
});
socket.on('article:update', ({ data }) => render(data.attributes));
socket.emit('unsubscribe-entity', { uid: 'api::article.article', documentId });
socket.emit('get-entity-subscriptions', ({ subscriptions }) => console.log(subscriptions));
ErrorMeaning
Entity subscriptions are disabledThe setting is off.
Invalid parameters: uid and documentId are requireduid is not an api:: uid or documentId is not a document id.
Not allowedAdmin socket, unknown content type, or no find/findOne for the role/token.
Entity not foundNo such entry (published only, while Only published content is on).
Maximum subscriptions (n) reachedThe per-client limit from the settings.
Rate limit exceededMore than ten subscribe requests per second.

Server code can use the same checks:

MethodReturns
subscribeToEntity(socketId, uid, documentId)Promise<{ success, uid, documentId, id } | { success, error }>
unsubscribeFromEntity(socketId, uid, documentId){ success, uid, documentId, id } | { success, error } (a Promise for a socket on another process: await it)
getEntitySubscriptions(socketId){ success, subscriptions: [{ uid, documentId, id }] } (a Promise for a socket on another process: await it)

emit() and emitIdentifier() accept broadcast: false to reach only the subscribers of data.documentId.

Not part of 6.0 ​

emitToEntity, getEntityRoomSockets, live preview field events (preview:*) and field-level diffs. See the migration guide for the reasons.

See also ​

Released under the MIT License. Updated and made better by @Schero94 · llms.txt