Skip to content

Getting started ​

From npm install to your first live event in about a minute.

Requirements ​

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

For Strapi 4 use version 2.x of the plugin.

1. Install ​

bash
npm install @strapi-community/plugin-io
bash
yarn add @strapi-community/plugin-io
bash
pnpm add @strapi-community/plugin-io

2. Watch a content type ​

js
module.exports = () => ({
  io: {
    enabled: true,
    config: {
      contentTypes: ['api::article.article'],
    },
  },
});
ts
export default () => ({
  io: {
    enabled: true,
    config: {
      contentTypes: ['api::article.article'],
    },
  },
});

Restart Strapi (npm run develop).

3. Allow reading ​

Clients receive what they may read through the REST API. For a quick test, give the Public role the find permission for Article in Settings > Users & Permissions plugin > Roles > Public.

4. Listen ​

bash
npm install socket.io-client
js
import { io } from 'socket.io-client';

const socket = io('http://localhost:1337');

socket.on('connect', () => console.log('connected', socket.id));
socket.on('article:publish', ({ data }) => console.log('published', data.attributes.title));
socket.on('article:delete', ({ data }) => console.log('deleted', data.documentId));

Publish an article in the Content Manager and watch the event arrive.

Browser on another origin?

A page served from another origin (for example http://localhost:3000) must be listed under Settings > Socket.IO > Settings > Allowed origins. Node scripts and mobile apps send no Origin header and are not affected.

Authenticate clients ​

js
// Users & Permissions JWT: the client joins its role's room
const socket = io(url, { auth: (cb) => cb({ strategy: 'jwt', token: getJwt() }) });

// Content API token (read-only, full-access or custom)
const socket = io(url, { auth: { strategy: 'api-token', token: process.env.STRAPI_TOKEN } });

A function for auth runs on every reconnect, so a refreshed JWT is picked up. Turn on Require authentication to refuse clients without a token. Failed handshakes only ever see Authentication failed.

What you get in the admin ​

  • Settings > Socket.IO > Settings: origins, limits, security, content events, roles, presence and monitoring. Changes apply without a restart.
  • Settings > Socket.IO > Monitoring: connected clients, rooms, events per second, admins online and the recent event log.
  • Homepage widgets: Socket.IO counters and Admins online.
  • Live presence in the Content Manager edit view.

Super Admins see everything. Grant the plugin's permissions to other roles in Settings > Administration panel > Roles > Plugins > IO.

Settings > Socket.IO > Settings

Troubleshooting ​

Nothing arrives. Check that the role or token has find on the content type, that the content type is watched, and, with Draft & Publish, that you listen to :publish (drafts are not sent while Only published content is on).

connect_error: Authentication failed. The JWT or token is invalid, expired or belongs to a blocked user. After 20 failures from one IP within a minute, that IP is locked out for the rest of the minute.

Browser shows a CORS error or a 400/403 on /socket.io/. Add the page's origin under Allowed origins.

strapi transfer stopped working. Upgrade to 6.0; see the README troubleshooting for #112.

Next steps ​

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