strapi-plugin-io

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

Requirements

The installation requirements are the same as Strapi itself and can be found in the documentation on the Quick Start page in the Prerequisites info card.

Supported Strapi versions

• v4.x.x

NOTE: While this plugin may work with the older Strapi versions, they are not supported, it is always recommended to use the latest version of Strapi.

Installation

npm install strapi-plugin-io

# or

yarn add strapi-plugin-io

Configuration

The plugin configuration is stored in a config file located at ./config/plugins.js.

Sample configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
module.exports = ({ env }) => ({
  // ...
  "io": {
    "enabled": true,
    "config": {
      "IOServerOptions" :{
        "cors": { "origin": "http://localhost:5000", "methods": ["GET"] },
      },
      "contentTypes": {
        "message": "*",
        "chat":["create"]
      },
      "events":[
        {
          "name": "connection",
          "handler": ({ strapi }, socket) => {
            strapi.log.info(`[io] new connection with id ${socket.id}`);
          },
        },
      ]
    },
  },
  // ...
});

The above configuration will do the following:

1. Set the IO server options.
2. Emit all events for the messages content type and only the create event for the chats content type.
3. Log the socket id of any newly connected sockets.

IMPORTANT NOTE: Make sure any sensitive data is stored in env files.

The Complete Plugin Configuration Object

Currently Supported Emit events

• find
• findOne
• delete
• create
• update
• publish
• unpublish
• createOrUpdate (single content type only)

Emit Syntax

All events emitted have the following syntax singularName:action.

Emitting Custom Events

The server socket instance is attached to the strapi object. Custom event can be emitted via the emit or raw method.

Emit

The emit function accepts a specific event format (api::singularName.singularName.actionName) and will automatically verify permissions for all strapi roles (rooms).

1
strapi.$io.emit("api::message.message.someCustomAction", data);

Raw

A raw emit will not verify any permissions before emitting.

Raw emit to all rooms

1
strapi.$io.raw("customEvent", data);

Raw emit to a specific room

1
strapi.$io.raw("customEvent", data, {room: "SOCKET_ID"});

Example Client Connections

Below are example client socket configurations.

Unauthenticated User connection

1
2
3
4
5
6
7
8
9
10
const { io } = require("socket.io-client");
const SERVER_URL = "http://localhost:1337";
const socket = io(SERVER_URL);

//  wait until socket connects before adding event listeners
socket.on("connect", () => {
  socket.on("message:update", (data) => {
    console.log(data)
  });
});

Authenticated User connection

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
const { io } = require("socket.io-client");
const SERVER_URL = "http://localhost:1337";
const JWT_TOKEN = "your users JWT token";

// token will be verified, connection will be rejected if not a valid JWT
const socket = io(SERVER_URL, {
  auth: { 
    token: JWT_TOKEN
  },
});

//  wait until socket connects before adding event listeners
socket.on("connect", () => {
  socket.on("message:update", (data) => {
    console.log(data)
  });
});

Bugs

If any bugs are found please report them as a Github Issue