A plugin for Strapi CMS that provides the ability for Socket IO integration

Latest version

v6.0.4

released November 18, 2026

npm install @strapi-community/plugin-io

Socket.IO for Strapi icon

@strapi-community/plugin-io

Real-time content events for Strapi 5 with Socket.IO, scoped by Strapi's own permissions.

npm version npm downloads CI build status License: MIT Strapi 5.38+ Documentation site

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.

Settings > Socket.IO > Monitoring in dark mode

Full documentation: https://strapi-community.github.io/plugin-io/

Contents

Requirements

Version
Strapi5.38 or later (tested with 5.63)
Node.js22.21+ or 24.9+ (up to 26, like Strapi 5.63)
Users & PermissionsOptional. Needed for user JWTs and the Public role room.

Quick start

npm install @strapi-community/plugin-io

config/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.

Content events

Events are named <singularName>:<action>. Content types are watched from the config (fixed) or chosen in the admin settings (editable).

ActionWhenPayload
createA document is created{ data: { id, attributes }, meta }
updateA document is updated{ data: { id, attributes }, meta }
publishA draft is published{ data: { id, attributes }, meta }
discardDraftA draft is reset to the published version{ data: { id, attributes }, meta }
unpublishA document is unpublished{ data: { documentId, locale? } }
deleteA document (locale) is deleted{ data: { documentId, locale? } }
  • Who receives an event: every Users & Permissions role and content API token with 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.
  • Drafts: with Draft & Publish, draft versions are not sent while Only published content is on (the default). Turn it off to send drafts to the roles that may read them.
  • Locales: one event per locale. Events are emitted after the database transaction commits.
  • Populate: populate refetches the entry with the same locale and status before it is sent.
  • Sanitizing: each audience gets the entry sanitized with its own permissions. Private fields, password fields, built-in secrets (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.

Authentication

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);
StrategyRoomNotes
jwtio-role-<role type>, e.g. io-role-authenticatedBlocked 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.
noneio-role-publicOnly 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:

kindKeys
publicrole
useruser.id, user.role, role, expiresAt (Users & Permissions user)
tokentoken.id, token.type, expiresAt
adminadmin.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.

Configuration

// 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:

OptionDefaultWhy
destroyUpgradefalseForeign upgrades (Strapi Data Transfer) are forwarded to Strapi instead of being closed.
maxHttpBufferSize1e5 (100 KB)Limits the size of messages clients send. Socket.IO's default is 1 MB.
cors / allowRequestfrom Allowed originsApplies 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, connectTimeoutfrom the admin settingsApplied to new connections without a restart.

Admin panel

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 > Socket.IO > Settings

Settings (plugin::io.settings.read / plugin::io.settings.update). Every setting applies to new connections without a restart:

SectionSettings
ConnectionsAllowed origins, maximum connections (0 = unlimited), ping interval, ping timeout, connection timeout
SecurityRequire authentication, limit client events (events per second per client), allowed IP addresses, blocked IP addresses (addresses and CIDR blocks)
Content eventsOnly published content, excluded fields, actions per content type (rows set in the config are read-only)
RolesWhether each Users & Permissions role may connect. What a role receives follows its permissions.
Entry subscriptionsAllow subscribe-entity, subscriptions per client (off by default)
Live presenceShow who is editing, show typing
MonitoringLog connections, keep an in-memory event log, event log size
Export and importDownload 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.

Settings > Socket.IO > Monitoring

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

Socket.IO homepage widget

Monitoring at 390 px width

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.

Live presence panel in the edit view

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.

Server API

// 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.

Security model

  • Admin routes require an authenticated admin plus the plugin permission (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.
  • Failed handshakes lock an IP out after 20 per minute (across all processes when they share a database). Unknown presence tokens count in a separate limit, so admins behind one office NAT do not lock out other clients.
  • Monitoring responses contain counts and admin display names only, never IP addresses, emails, tokens or socket ids.
  • The settings document is validated with a strict schema (unknown keys rejected, every list and number bounded). Invalid input returns 400 with field paths.
  • Entity subscriptions need read permission of the client's role or API token, are limited per client and to ten requests per second, use reserved per-audience rooms and are re-checked on every event.
  • Presence events are accepted only from admin sockets, need Content Manager read permission for the content type and are rate limited. Admin sockets are re-checked against the admin's current permissions and Strapi session.
  • Browser origins are checked for polling and WebSocket. An empty Allowed origins list means same origin only.
  • Clients can be rate limited per socket; the connection count, IP rules and origins are checked in the handshake.
  • Logs never contain tokens, emails or IP addresses.

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.

Performance

  • Delivery: one sanitize pass per room that has listeners. Rooms without sockets are skipped (with the in-memory adapter), so hundreds of API tokens cost nothing until they connect. On the 5,000-article test host a publish with populated relations adds 10 queries for the plugin (one refetch plus an occasional audience-cache rebuild), independent of the number of roles and tokens.
  • Audience cache: roles, tokens and their permissions are loaded with one query per kind and cached for 10 seconds; role, permission and token changes clear the cache.
  • Re-checks: every five minutes and right after a user, admin, API token or Strapi session changes. Checks run in one batch per kind: one query for all affected users, one for tokens, one for admins, plus one per distinct session. On a test host with 200 connected sockets, updating an unrelated user cost 427 SQL queries before this targeting existed; now the plugin adds none (the update itself takes Strapi 22 to 27 queries).
  • Populate: only what you configure, refetched once per event.
  • Memory: presence tokens are capped per admin and globally; monitoring keeps fixed-size counters and a bounded event log.
  • Several processes: a successful handshake does not touch the shared tables; a failed one costs one atomic 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.

Running several instances

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.

  • Adapter: '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.
  • Shared automatically once an adapter is attached, in pm2 cluster mode or on Railway: one-time admin presence tokens (hashed, used exactly once on any process), settings (revision with compare-and-swap; a concurrent save gets 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.
  • Warnings at boot for several processes without an adapter, long-polling with several processes, and Railway without server.proxy.koa. The Monitoring page shows the first one too.
  • Database restarts: when the Postgres adapter loses its LISTEN connection (restart, failover, 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.
  • Server helpers that take a 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.
  • Connection budget: each process has its own knex pool plus 2 adapter connections. 8 processes with Strapi's default pool of 10 need 96 PostgreSQL connections; set 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.

Upgrading from 5.x

6.0 contains breaking changes. The full list is in CHANGELOG.md. In short:

  1. Delivery follows read permissions. Give roles and tokens find (or findOne) on the content types they should receive. Create or update permissions alone no longer deliver events.
  2. Publish is its own event. Publishing used to emit :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.
  3. Drafts are not sent by default. Turn off Only published content to send drafts.
  4. Delete events go to readers only and include locale for localized content.
  5. Rooms: API-token rooms are io-token-<id>; custom role rooms are io-role-<role type> (io-role-public and io-role-authenticated are unchanged).
  6. Settings are enforced. Settings stored by 5.x were never applied. On the first start, unused keys (Redis, namespaces, live preview, field-level changes) are dropped, entity subscriptions stay off until you turn them on, and the old default origin http://localhost:3000 and the old default connection limit of 1000 are reset. Review Settings > Socket.IO after upgrading.
  7. Admin permissions. Only Super Admins can open the plugin pages until you grant the new permissions to other roles.
  8. Removed: the 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.
  9. Message size. maxHttpBufferSize defaults to 100 KB. Raise it in socket.serverOptions if clients send larger messages.
  10. Allowed origins apply to WebSocket too. 5.x accepted WebSocket clients from any origin. With an empty list only same-origin browsers (plus server.url / admin.url) may connect; list your frontends.
  11. Admin sockets use socket.data.admin. Presence sockets no longer appear as socket.data.user, and config.events handlers skip them unless the event sets admin: true.
  12. Node.js 22.21+ or 24.9+ and Strapi 5.38+ are required (Strapi ships Design System 2.2 with its admin from 5.38.0 on).
  13. hooks.init receives { strapi, $io, io } and runs before the plugin handshake, as in 5.x. Middleware added there runs before authentication.
  14. Several processes (replicas, pm2 cluster): set 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.

Troubleshooting

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.

Development

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 verify

npm 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).

Contributing

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.

License

MIT

Submit your content

Share your work with the community and get it listed in the Strapi ecosystem for everyone to discover and use.

Submit
Submit your content