Registry / messaging / egg-websocket-plugin

egg-websocket-plugin

library3.0.0-beta.0jsnpmunverified

Official WebSocket plugin for the Egg.js framework (current version 3.0.0-beta.0). It integrates WebSocket endpoints into Egg's routing and controller system, supporting route parameters, app-level and route-level middleware, Redis pub/sub for broadcasting, and room-based messaging. Unlike socket.io, it does not require sticky sessions and directly wraps the ws library. It is compatible with Egg 3.x and ships TypeScript definitions. Release cadence is tied to Egg major versions; v3 corresponds to Egg 3.

messaging

npm install egg-websocket-plugin

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EGG-WEBSOCKET-PLUG

egg-websocket-plugin

messagingjavascriptv3.0.0-beta.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Controller

✓ import { Controller } from 'egg';

✗ import { Controller } from 'egg-websocket-plugin';

Controller comes from the 'egg' package, not the plugin.

app.ws.route

✓ app.ws.route('/ws', app.controller.home.hello);

✗ app.router.ws('/ws', app.controller.home.hello);

WebSocket routes are registered via app.ws.route, not app.router.

app.ws.use

✓ app.ws.use(async (ctx, next) => { ... });

✗ app.use(async (ctx, next) => { ... });

app.ws.use adds WebSocket-specific global middleware; app.use adds HTTP middleware only.

Demonstrates enabling the plugin, defining a WebSocket route, and handling messages in a controller.

// config/plugin.js exports.websocket = { enable: true, package: 'egg-websocket-plugin', }; // app/router.js app.ws.route('/ws', app.controller.home.hello); // app/controller/home.js import { Controller } from 'egg'; export default class HomeController extends Controller { async hello() { const { ctx } = this; ctx.websocket.on('message', (msg) => { console.log('received:', msg); }); ctx.websocket.send('Hello from Egg!'); } }

Debug

Known issues

gotchaWebSocket global middleware must be registered before any routes; otherwise, earlier routes won't use them.

fix

Always call app.ws.use() before any app.ws.route() calls.

affects: >=1.0.0

breakingVersion 3.0.0+ requires Egg 3.x (Node >=14.20.0). Egg 2.x users must install egg-websocket-plugin@1.0.1.

fix

Use egg-websocket-plugin@1.0.1 for Egg 2.x projects.

affects: >=3.0.0

deprecatedThis package is still in beta (3.0.0-beta.0). Consider it pre-release; API may change.

fix

Pin to exact version and upgrade with caution.

affects: 3.0.0-beta.x

gotchaIf you have HTTP middleware that conflicts with WebSocket (e.g., session middleware), you may need to disable app middleware for WebSocket via config.websocket.useAppMiddlewares = false.

fix

Set `config.websocket = { useAppMiddlewares: false }` in config.default.js.

affects: >=1.0.0

gotchaRedis pub/sub is optional but requires the ioredis package. Ensure it is installed and configured correctly.

fix

Install ioredis as a project dependency; configure redis in config.websocket.redis.

affects: >=1.0.0

Errors

Common errors & fixes

Error: this function can only be use in websocket router

Calling ctx.websocket in a non-WebSocket route.

fix

Ensure the route is defined with app.ws.route(), not app.router.

TypeError: app.ws.use is not a function

The plugin is not enabled or the app.ws object hasn't been initialized because routes are configured before plugin loading.

fix

Check that the plugin is enabled in config/plugin.js and that routes are defined after the plugin is loaded (usually in app/router.js).

Error: Can't set headers after they are sent to the client

Trying to send HTTP response after WebSocket upgrade.

fix

Do not use ctx.body or similar HTTP methods inside WebSocket controller actions; use ctx.websocket.send instead.

Upgrade

Version history

3.0.0-beta.0latest on npm

Audit

Dependencies

eggrequiredpeer dependency – requires Egg framework v3

ioredisoptionaloptional – needed only for Redis pub/sub broadcasting

Agent activity

28 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/flarestart/egg-websocket-plugin ↗

packageegg-websocket-plugin ↗

homepagehttps://github.com/flarestart/egg-websocket-plugin#readme ↗