Reload plugin ​

The reload plugin preserves approved room memberships and transferable socket.data across page reloads. Configure it on both the server and the client.

Installation ​

Install the plugins package in both your backend and frontend projects:

npm install @jcbuisson/express-x-plugins

Server setup ​

reloadPlugin allows page reloads while preserving the information attached to the connection (room memberships, socket.data).

Transfers use a short-lived one-time token, and cached state is isolated per ExpressX application.

On the server, it caches each socket's rooms and data just before disconnection, then listens for a token-authenticated cnx-transfer message from the reconnecting client. Fresh socket.data created by connection middleware takes precedence over cached values.

import { expressX } from '@jcbuisson/express-x/server'
import { reloadPlugin } from '@jcbuisson/express-x-plugins/reload-server'

const app = expressX()
await reloadPlugin(app, {
   // Required to restore application rooms. The secure default is deny.
   authorizeRoomRestore: async ({ socket, room }) => {
      // Populate allowedRooms from freshly validated authentication state.
      return Array.isArray(socket.data.allowedRooms)
         && socket.data.allowedRooms.includes(room)
   },
})

The client-side reloadPlugin must also be configured.

Socket.IO recovery middleware runs again by default. Set skipRecoveryMiddlewares: true in the expressX configuration only if stale authentication and authorization have been addressed by another explicit revalidation mechanism.

Cached state lifetime ​

Set reloadTransferTtlMs in the expressX configuration to control how long the reload server plugin caches state. The default is 120000 milliseconds.

const app = expressX({ reloadTransferTtlMs: 120000 })

Client setup ​

reloadPlugin allows page reloads while preserving the information attached to the connection (room memberships, socket.data).

The server-side reloadPlugin must be configured.

import { io } from 'socket.io-client'
import { createClient } from '@jcbuisson/express-x/client'
import { reloadPlugin } from '@jcbuisson/express-x-plugins/reload-client'

const socket = io('http://localhost:8000', { transports: ['websocket'] })
const app = createClient(socket)
await reloadPlugin(app)

It uses a short-lived, one-time transfer token to preserve approved socket rooms and transferable socket.data across page reloads. On reconnect, it emits a cnx-transfer message to the server to copy the previous socket's state onto the new connection.

reloadPlugin uses sessionStorage internally to track the previous socket ID and transfer token. Token listeners and acknowledgement listeners are bounded and cleaned up across reconnects.

Room restoration is denied by default on the server. See the server-side reloadPlugin for authorization configuration.