Getting started
From npm install to your first live event in about a minute.
Requirements
| Version | |
|---|---|
| Strapi | 5.38 or later (tested with 5.62) |
| Node.js | 22.21+ or 24.9+ (up to 26, like Strapi 5.62) |
| Users & Permissions | Optional. Needed for user JWTs and the Public role room. |
For Strapi 4 use version 2.x of the plugin.
1. Install
npm install @strapi-community/plugin-ioyarn add @strapi-community/plugin-iopnpm add @strapi-community/plugin-io2. Watch a content type
module.exports = () => ({
io: {
enabled: true,
config: {
contentTypes: ['api::article.article'],
},
},
});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
npm install socket.io-clientimport { 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
// 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.

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
- Content types: actions, populate, payloads
- Custom events: handle client events safely
- Plugin configuration: every option
- Migration guide: upgrading from 5.x