
A plugin for Strapi CMS that provides the ability for Socket IO integration
released November 18, 2026
npm install @strapi-community/plugin-io
Real-time content events for Strapi 5 with Socket.IO, scoped by Strapi's own permissions.
The plugin attaches a Socket.IO server to Strapi's HTTP server and sends an event whenever a watched document is created, updated, published, unpublished, has its draft discarded or is deleted. Each client receives only what its role or API token may read through the REST API, sanitized with the same Content API sanitizer Strapi uses.
It also adds Settings > Socket.IO (settings and live monitoring), two homepage widgets and a live presence panel in the Content Manager, all built from the Strapi Design System.

Full documentation: https://strapi-community.github.io/plugin-io/
| Version | |
|---|---|
| Strapi | 5.38 or later (tested with 5.63) |
| Node.js | 22.21+ or 24.9+ (up to 26, like Strapi 5.63) |
| Users & Permissions | Optional. Needed for user JWTs and the Public role room. |
npm install @strapi-community/plugin-ioconfig/plugins.js:
module.exports = {
io: {
enabled: true,
config: {
contentTypes: ['api::article.article'],
},
},
};Give the Public role (or any role) the find permission for Article in Settings > Users & Permissions > Roles, then connect from a frontend:
import { io } from 'socket.io-client';
const socket = io('https://cms.example.com');
socket.on('article:publish', ({ data }) => console.log('Published', data.attributes.title));
socket.on('article:delete', ({ data }) => console.log('Deleted', data.documentId, data.locale));Browsers on another origin must be listed under Settings > Socket.IO > Settings > Allowed origins. With an empty list only the Strapi host itself and the origins of server.url / admin.url may connect, for polling and WebSocket alike. Node scripts and mobile apps send no Origin header and are not affected.
Events are named <singularName>:<action>. Content types are watched from the config (fixed) or chosen in the admin settings (editable).
| Action | When | Payload |
|---|---|---|
create | A document is created | { data: { id, attributes }, meta } |
update | A document is updated | { data: { id, attributes }, meta } |
publish | A draft is published | { data: { id, attributes }, meta } |
discardDraft | A draft is reset to the published version | { data: { id, attributes }, meta } |
unpublish | A document is unpublished | { data: { documentId, locale? } } |
delete | A document (locale) is deleted | { data: { documentId, locale? } } |
find or findOne permission on the content type. Read-only and full-access tokens receive all events. Roles that may only create or update receive nothing.populate refetches the entry with the same locale and status before it is sent.password, resetPasswordToken, apiKey, secret, ...), config.sensitiveFields and the Excluded fields setting are removed. If sanitizing fails, that audience is skipped and nothing is sent.Events come from Strapi's Document Service middleware (strapi.documents.use). Writes made directly with strapi.db.query() do not emit events.
Clients authenticate in the Socket.IO handshake:
// Users & Permissions JWT (legacy and refresh mode)
io(url, { auth: { strategy: 'jwt', token: userJwt } });
// Content API token
io(url, { auth: { strategy: 'api-token', token: apiToken } });
// No token: the client joins the Public role (unless "Require authentication" is on)
io(url);| Strategy | Room | Notes |
|---|---|---|
jwt | io-role-<role type>, e.g. io-role-authenticated | Blocked and unconfirmed users are rejected. The socket is disconnected when the JWT expires, the user is blocked or changes role, or (refresh mode) the Strapi session behind the token is revoked. |
api-token (also apiToken, token) | io-token-<token id> | Content API tokens only; admin tokens are rejected. Disconnected when the token is deleted or expires. |
| none | io-role-public | Only while Require authentication is off. |
Failed handshakes return one generic message (Authentication failed). After 20 failures from the same IP within a minute, that IP is locked out for the rest of the minute. The client IP follows Strapi's server.proxy settings.
For refresh-mode JWTs, pass a function so that reconnects use a fresh access token:
io(url, { auth: (cb) => getAccessToken().then((token) => cb({ strategy: 'jwt', token })) });The handshake stores the client on socket.data. Check socket.data.kind before you trust an id:
kind | Keys |
|---|---|
public | role |
user | user.id, user.role, role, expiresAt (Users & Permissions user) |
token | token.id, token.type, expiresAt |
admin | admin.id, admin.firstname, admin.lastname (presence panel, admin ids) |
Admin presence sockets never carry socket.data.user, and config.events handlers skip them unless the event sets admin: true.
// config/plugins.js
module.exports = ({ env }) => ({
io: {
enabled: true,
config: {
// Fixed watch list. Strings watch every action.
contentTypes: [
'api::article.article',
{ uid: 'api::page.page', actions: ['publish', 'unpublish', 'delete'], populate: ['seo', 'cover'] },
],
// Extra field names that are never sent.
sensitiveFields: ['internalNotes'],
// Custom client events. Handlers get ({ strapi, io }, socket, ...args).
// Admin presence sockets are skipped unless an event sets `admin: true`.
events: [
{ name: 'connection', handler: ({ strapi }, socket) => strapi.log.debug(`[io] ${socket.data.kind} connected`) },
{ name: 'ping', handler: (_ctx, socket) => socket.emit('pong') },
],
// Runs once during bootstrap (awaited), before the plugin handshake is added.
// `$io` and `io` are the same object. Use it for adapters, middleware or namespaces.
hooks: {
async init({ strapi, $io }) {},
},
// Socket.IO server options. Values here win over the admin settings.
socket: {
serverOptions: {
// cors: { origin: ['https://app.example.com'] },
// maxHttpBufferSize: 1e6,
},
// Several processes: see "Running several instances".
// adapter: 'postgres',
// websocketOnly: true,
},
},
},
});Defaults the plugin sets unless you override them in socket.serverOptions:
| Option | Default | Why |
|---|---|---|
destroyUpgrade | false | Foreign upgrades (Strapi Data Transfer) are forwarded to Strapi instead of being closed. |
maxHttpBufferSize | 1e5 (100 KB) | Limits the size of messages clients send. Socket.IO's default is 1 MB. |
cors / allowRequest | from Allowed origins | Applies the same origin rule to polling and WebSocket. Same-origin requests, server.url / admin.url origins and clients without an Origin header are always allowed. |
pingInterval, pingTimeout, connectTimeout | from the admin settings | Applied to new connections without a restart. |
The plugin adds a Socket.IO section under Settings with two pages, two homepage widgets and a side panel in the Content Manager. All screens use the Strapi Design System and follow the layout of the native settings pages.

Settings (plugin::io.settings.read / plugin::io.settings.update). Every setting applies to new connections without a restart:
| Section | Settings |
|---|---|
| Connections | Allowed origins, maximum connections (0 = unlimited), ping interval, ping timeout, connection timeout |
| Security | Require authentication, limit client events (events per second per client), allowed IP addresses, blocked IP addresses (addresses and CIDR blocks) |
| Content events | Only published content, excluded fields, actions per content type (rows set in the config are read-only) |
| Roles | Whether each Users & Permissions role may connect. What a role receives follows its permissions. |
| Entry subscriptions | Allow subscribe-entity, subscriptions per client (off by default) |
| Live presence | Show who is editing, show typing |
| Monitoring | Log connections, keep an in-memory event log, event log size |
| Export and import | Download the saved settings as JSON (no secrets); import a file, review the changed values and save |
Import sends the file to POST /io/settings/validate (needs plugin::io.settings.update), which checks it with the same strict schema as Save and stores nothing. The changed values are listed in a confirmation dialog and replace the form values; Save stores them.
Monitoring (plugin::io.monitoring.read; reset and test events need plugin::io.monitoring.manage): connected clients by type, active rooms, events per second, events sent, admins online with the entries they edit, and the event log. Entries in content types the viewer may not read in the Content Manager are counted, not named. Test events go to every connected client; names used by content and presence events are refused.

Homepage widgets: Socket.IO (four counters) and Admins online. Both need plugin::io.monitoring.read.

Live presence panel in the Content Manager edit view: shows the other admins editing the same entry and, optionally, which field they are typing in. Admins only join the presence room of content types they may read in the Content Manager. The panel connects with a one-time token per connection attempt (at most five unused tokens per admin) and shows no email addresses. The connection ends when the admin logs out, the admin session expires or the account is deactivated.

Screenshots come from a local test host with synthetic data.
Strapi grants new permissions to Super Admins only. Give other roles access in Settings > Administration Panel > Roles > Plugins > IO.
// Content events (also used internally)
await strapi.$io.emit({ event: 'publish', schema: 'api::article.article', data: entry });
await strapi.$io.emitIdentifier({ event: 'delete', schema: 'api::article.article', data: { documentId, locale } });
// Custom events (sensitive fields removed). Without rooms they go to every client.
await strapi.$io.raw({ event: 'maintenance', data: { at: '22:00' }, rooms: ['io-role-authenticated'] });
// Helpers
await strapi.$io.joinRoom(socketId, 'premium'); // plugin rooms (io-role-, io-token-, io-admin-, io-entity-, presence:) are refused
await strapi.$io.leaveRoom(socketId, 'premium');
await strapi.$io.getSocketsInRoom('premium');
strapi.$io.sendPrivateMessage(socketId, 'notice', data);
strapi.$io.broadcast(socketId, 'notice', data); // everyone except socketId
strapi.$io.emitToNamespace('chat', 'notice', data);
await strapi.$io.disconnectSocket(socketId);
await strapi.$io.subscribeToEntity(socketId, 'api::article.article', documentId); // same checks as subscribe-entity
await strapi.$io.unsubscribeFromEntity(socketId, 'api::article.article', documentId);
await strapi.$io.getEntitySubscriptions(socketId);
await strapi.$io.revalidateSockets(); // every authenticated socket
await strapi.$io.revalidateSockets(['user'], { ids: [userId] }); // only this user's sockets
strapi.$io.server; // the Socket.IO Server
strapi.$io.namespaces; // { '': Namespace, chat: Namespace, ... }
// Monitoring service (counts only)
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);Entity subscriptions. With Entry subscriptions on, clients follow single entries:
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 });A subscription needs find or findOne on the client's own role or API token and an existing entry. Every event is sanitized with those permissions, and read permission is checked again for each event. Subscribers also receive events of content types and actions that are not broadcast under Events, and a client in both its role room and an entry room gets each event once. Admin sockets cannot subscribe. The IO class reference lists the errors.
Namespaces created with strapi.$io.server.of('/name'), for example in hooks.init, use the same handshake as the default namespace. TypeScript types ship with the package (types.d.ts) and add strapi.$io to Core.Strapi.
admin::hasPermissions). The presence session route only requires an authenticated admin; it keeps at most five unused tokens per admin and answers 429 when 10,000 are pending. A token holds the admin id and session id only; permissions are loaded from the database when it is used. With several processes tokens are stored as SHA-256 hashes and used with one DELETE, so each works exactly once.400 with field paths.Report vulnerabilities privately through GitHub security advisories.
npm audit --omit=dev reports 0 vulnerabilities for the published package. The development tree overrides nodemailer, the zod of koa-body and @hono/node-server to patched releases. The advisories left in it (zod 3 inside koa-session, stream-json, react-router 6, minimatch/glob in build tools, deepmerge) have no compatible fix and are not shipped with the plugin; the migration guide lists each one and why it stays.
UPDATE. Each process writes one heartbeat every 10 seconds and reads new control signals every 3 seconds (one indexed query each). The admin ability and the client IP stay out of socket.data, so fetchSockets() across servers sends only identity fields.Two Railway replicas with pm2 -i 4 each are eight Node.js processes that share one database and no memory. They act as one Socket.IO server when you set three things:
npm install @socket.io/postgres-adapter pg # or: @socket.io/redis-adapter ioredis// config/plugins.js
io: {
enabled: true,
config: {
contentTypes: ['api::article.article'],
socket: {
adapter: 'postgres', // or { type: 'redis', url: env('REDIS_URL') }
websocketOnly: true, // no long-polling: Railway and pm2 have no sticky sessions
},
},
},
// config/server.js (Railway passes the client IP in X-Real-IP)
proxy: { koa: true, ipHeader: 'X-Real-IP', maxIpsCount: 1 },Clients connect with transports: ['websocket']. The admin already does.
'postgres' uses @socket.io/postgres-adapter (LISTEN/NOTIFY) on its own pool of 2 connections and Strapi's PostgreSQL connection; it needs a direct or session-mode connection (not PgBouncer in transaction mode). { type: 'redis' } uses @socket.io/redis-adapter with ioredis. A function returns any other adapter. The packages are optional peer dependencies and load only when configured.409 and the admin offers a reload), revocations of users, tokens, admins and sessions, the audience cache, the failed-handshake lockout, the maxConnections total, presence editor lists and the monitoring totals. Four small tables (plugin_io_presence_tokens, plugin_io_counters, plugin_io_nodes, plugin_io_signals) hold this state; one plain process writes none of it.server.proxy.koa. The Monitoring page shows the first one too.idle_session_timeout), the process keeps running and logs a warning. Events stay on the local process until the adapter reconnects 1 to 3 s later; settings, revocations and lockouts keep travelling through the signal table.socketId (joinRoom, leaveRoom, disconnectSocket, the entity subscription helpers) act only on the socket with exactly that id, on any process, and return a Promise for a socket on another process. A room name passed as socketId selects nobody.database.connection.pool.max to about 6 to stay well under a limit of 100.Full guide with pm2, Redis, pool sizing and the remaining limits: Running several instances.
With an adapter that spans several servers, a server cannot see which entries are followed on the other servers. While Entry subscriptions is on, every change to a content type that is not broadcast is therefore sanitized and sent to the entry rooms of each reading audience. Leave Entry subscriptions off if you do not use them.
6.0 contains breaking changes. The full list is in CHANGELOG.md. In short:
find (or findOne) on the content types they should receive. Create or update permissions alone no longer deliver events.:delete and :create; it now emits :publish. Unpublish and discard draft emit :unpublish and :discardDraft. If you limit actions in the config, add the new ones you need.locale for localized content.io-token-<id>; custom role rooms are io-role-<role type> (io-role-public and io-role-authenticated are unchanged).http://localhost:3000 and the old default connection limit of 1000 are reset. Review Settings > Socket.IO after upgrading.security service, the scaffold route GET /api/io, live preview field events and field-level diffs (the migration guide explains why). Restored: entity subscriptions (with permission checks, off by default; clients pass the documentId) and settings export and import.maxHttpBufferSize defaults to 100 KB. Raise it in socket.serverOptions if clients send larger messages.server.url / admin.url) may connect; list your frontends.socket.data.admin. Presence sockets no longer appear as socket.data.user, and config.events handlers skip them unless the event sets admin: true.hooks.init receives { strapi, $io, io } and runs before the plugin handshake, as in 5.x. Middleware added there runs before authentication.socket.adapter ('postgres' or { type: 'redis' }) instead of attaching an adapter in hooks.init, add socket.websocketOnly: true without sticky sessions, and size database.connection.pool.max for two extra adapter connections per process. The plugin then creates four plugin_io_* tables on first start. See Running several instances.The migration guide explains each step with code.
strapi transfer fails with 504 or 524 behind a proxy (#112). Socket.IO's upgrade listener stopped Node from passing the Data Transfer WebSocket to Strapi. The plugin tells Node (shouldUpgradeCallback, Node 22.21+ / 24.9+) to accept upgrades only on the Socket.IO path, so every other request, including a POST with an Upgrade: h2c header and a body, reaches Strapi exactly as without the plugin. If you attach your own upgrade listener, the plugin leaves those upgrades to you. On an older, unsupported Node.js the plugin logs a warning at startup.
strapi ts:generate-types or shutdown hangs (#109). The plugin no longer closes Strapi's HTTP server, and all its timers are released on destroy.
Clients receive nothing. Check that the role or token has find on the content type, that the content type is watched (config or settings) and, for Draft & Publish, that you listen to :publish or turned off Only published content.
Browser connection fails with a CORS, 400 or 403 error. Add the frontend origin under Allowed origins, or set socket.serverOptions.cors and allowRequest.
A custom handler sees socket.data.user as undefined. The client is an admin presence socket or a public/token client. Check socket.data.kind.
hooks.init failed in the log. The hook threw; Strapi started without what it sets up (for example the Redis adapter). Fix the error shown in the log.
npm ci
npm run lint # ESLint 10 flat config
npm run format:check # Prettier
npm run build # @strapi/sdk-plugin
npm test # node --test
npm run test:types # checks types.d.ts with tsc
npm run test:admin # admin entry points in React StrictMode (jsdom, fake network)
npm run test:e2e # e2e suites against a running Strapi app (see below)
npm run test:e2e:app # scaffolds a Strapi 5.63 app with the packed plugin and runs the e2e suites (as CI does)
npm run test:cluster # 8 processes (2 pm2 daemons x 4 workers) on PostgreSQL behind a non-sticky balancer (CONTRIBUTING.md)
npm run verifynpm run test:admin renders every admin entry point (the Settings and Monitoring pages with the test event dialog, both homepage widgets, the Live presence side panel of the Content Manager edit view and the initializer) inside React.StrictMode with the providers of the Strapi admin, in jsdom with a fake network and a counting fake of socket.io-client. It fails on a mutation sent twice, a read repeated without aborting the first one, an interval, listener, socket or observer left after unmount, and any console error or warning. A separate CI job runs the same tests against React 19 for information only: the plugin's peer range is React 18, like the Strapi 5 admin.
npm run test:e2e runs the admin regression suite (Settings form, unsaved-changes guard, export and import, Monitoring, homepage widgets, 390 px and dark mode, read-only RBAC) in a standalone Chromium and the socket/API suite (per-audience delivery, entity subscriptions, settings import check, #112 upgrades, Upgrade: h2c bodies). Point it at a Strapi app with the plugin installed: IO_E2E_URL=http://127.0.0.1:1337 IO_E2E_EMAIL=... IO_E2E_PASSWORD=... IO_E2E_TOKEN=<full-access API token> npm run test:e2e (optionally IO_E2E_VIEWER_EMAIL / IO_E2E_VIEWER_PASSWORD for an admin with read-only plugin permissions). Run npx playwright install chromium once. Without these variables the tests are skipped.
npm run build && npm run test:e2e:app does all of that for you: it scaffolds a Strapi 5.63 app outside the repository (SQLite, the synthetic content types in tests/e2e/app, loopback-only egress), installs the packed plugin, seeds admins and a token with random per-run secrets that are never printed, and runs both suites. The app installs from the committed tests/e2e/app/package-lock.json with npm ci --ignore-scripts; only better-sqlite3 runs its install script (npm rebuild better-sqlite3). Options: --port (default 1357), --dir, --strapi (another exact Strapi version, resolved without the committed lockfile; CI runs the 5.38.0 peer floor this way), --overrides (apply this repo's npm overrides to the app), --update-lock (re-resolve the app and rewrite its lockfile, after changing the Strapi version or the plugin's dependencies) and --keep. CI runs it on Node 22 and 24.
Commits follow Conventional Commits. semantic-release publishes releases from main and folds the [Unreleased] section of CHANGELOG.md into the release notes (scripts/release-unreleased.mjs).
Bug reports and pull requests are welcome. Please open an issue first for larger changes and add a test for every fix. CONTRIBUTING.md lists the checks to run before you push, the cluster acceptance run and the admin UI conventions.
Share your work with the community and get it listed in the Strapi ecosystem for everyone to discover and use.
Submit
