Skip to content

Content types ​

A watched content type sends an event after every matching Document Service action. The event goes to each Users & Permissions role and content API token that may read the type, sanitized with that audience's permissions.

Watch everything ​

js
// config/plugins.js
module.exports = {
  io: {
    enabled: true,
    config: {
      contentTypes: ['api::article.article', 'api::category.category'],
    },
  },
};

A string watches all six actions.

ActionEventWhenPayload
createarticle:createA document is created{ data: { id, attributes }, meta: {} }
updatearticle:updateA document is updated{ data: { id, attributes }, meta: {} }
publisharticle:publishA draft is published{ data: { id, attributes }, meta: {} }
discardDraftarticle:discardDraftA draft is reset to the published version{ data: { id, attributes }, meta: {} }
unpublisharticle:unpublishA document is unpublished{ data: { documentId, locale? } }
deletearticle:deleteA document, or one of its locales, is deleted{ data: { documentId, locale? } }

The event name uses the content type's singularName.

Pick actions ​

js
contentTypes: [
  { uid: 'api::article.article', actions: ['publish', 'unpublish', 'delete'] },
  { uid: 'api::order.order', actions: ['create'] },
],

Editors can also watch API content types and toggle actions in Settings > Socket.IO > Settings > Content events. Types set in the config show there as read-only rows.

Populate relations ​

js
contentTypes: [
  { uid: 'api::article.article', populate: ['author', 'cover'] },
  { uid: 'api::page.page', populate: { seo: { fields: ['metaTitle'] } } },
  { uid: 'api::product.product', populate: '*' },
],

Before the event is sent, the entry is fetched again with the same locale and status and the given populate. Relations arrive in the v4-style shape { data: { id, attributes } }:

js
socket.on('article:publish', ({ data }) => {
  const author = data.attributes.author?.data?.attributes;
  console.log(data.attributes.title, 'by', author?.username);
});

A role that may not read the related type receives the entry without that relation. Populate only what clients need: every relation costs a query per event.

Drafts ​

With Draft & Publish, draft versions are not sent while Only published content is on (the default). Listen to :publish for new content. Turn the setting off to send create and update for drafts to the roles that may read them.

Locales ​

Each locale is its own event. Delete and unpublish payloads include locale for localized content:

js
socket.on('article:delete', ({ data }) => removeFromList(data.documentId, data.locale));

Keep a list in sync ​

js
const articles = new Map(); // documentId -> attributes

const upsert = ({ data }) => articles.set(data.attributes.documentId, data.attributes);
const remove = ({ data }) => articles.delete(data.documentId);

socket.on('article:publish', upsert);
socket.on('article:update', upsert);
socket.on('article:unpublish', remove);
socket.on('article:delete', remove);

Load the initial list through the REST API, then apply events. After a reconnect, reload the list, since events sent while a client was offline are not replayed.

What is never sent ​

  • Fields marked private and password fields (Strapi's Content API sanitizer).
  • Fields the audience may not read.
  • Built-in secret names (password, resetPasswordToken, apiKey, secret, ...), config.sensitiveFields and the Excluded fields setting.

If sanitizing fails for an audience, that audience gets nothing. The plugin never falls back to the raw entry.

Events from your own code ​

Events come from the Document Service, so strapi.documents(uid).update(...) in your services emits them too. strapi.db.query() writes do not. To send something yourself:

js
// sanitized per audience, like the automatic events
await strapi.$io.emit({ event: 'update', schema: 'api::article.article', data: entry });

// a custom event, sensitive keys removed
await strapi.$io.raw({ event: 'stock:low', data: { sku: 'A-1', left: 3 }, rooms: ['io-role-authenticated'] });

Troubleshooting ​

SymptomCheck
No events at allThe role or token has find or findOne on the type. The type is watched.
create arrives but not draftsOnly published content is on (default). Listen to :publish.
Relation missingIt is not in populate, or the audience may not read the related type.
Writes from a script send nothingThe script uses strapi.db.query(). Use strapi.documents().

See also ​

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