{"id":18473,"library":"koa-easy-ws","title":"koa-easy-ws","description":"Simple, composable Koa middleware for WebSocket handling. Version 2.1.0, actively maintained. Integrates the `ws` library as a peer dependency. Differentiates itself by being minimal (44 SLOC), unopinionated, and fully composable with other Koa middleware and routers. Supports custom context property names and passing options to the underlying `ws` server. Ships TypeScript types. Requires manual installation of `ws` and `koa` peer dependencies.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/b3nsn0w/koa-easy-ws","tags":["javascript","koa","websocket","ws","typescript"],"install":[{"cmd":"npm install koa-easy-ws","lang":"bash","label":"npm"},{"cmd":"yarn add koa-easy-ws","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-easy-ws","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for WebSocket server","package":"ws","optional":false},{"reason":"Peer dependency, Koa framework","package":"koa","optional":false}],"imports":[{"note":"ES module import, default export.","wrong":"const websocket = require('koa-easy-ws')","symbol":"websocket","correct":"import websocket from 'koa-easy-ws'"},{"note":"Must call as a function to configure middleware.","wrong":"app.use(websocket)","symbol":"websocket() call","correct":"app.use(websocket())"},{"note":"Access the underlying ws server instance for advanced configuration.","wrong":"","symbol":"websocket.server","correct":"const wsServer = websocket().server"}],"quickstart":{"code":"import Koa from 'koa';\nimport websocket from 'koa-easy-ws';\n\nconst app = new Koa();\napp.use(websocket());\n\napp.use(async (ctx) => {\n  if (ctx.ws) {\n    const ws = await ctx.ws();\n    ws.send('hello from koa-easy-ws');\n  } else {\n    ctx.body = 'HTTP response';\n  }\n});\n\napp.listen(3000);","lang":"typescript","description":"Shows basic setup: import, middleware registration, WebSocket handling with ctx.ws, and fallback HTTP response."},"warnings":[{"fix":"Use await ctx.ws() to get the ws instance.","message":"In version 2.x, ctx.ws is now a function returning a Promise, not a ws instance directly.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Run: npm install ws koa","message":"Must install ws and koa as peer dependencies manually.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use app.use(websocket())","message":"Middleware must be called as a function (websocket()) not just referenced.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use import easyWs from 'koa-easy-ws' or const { default: easyWs } = require('koa-easy-ws')","message":"The default export name 'websocket' may be confused with the 'ws' library; use clear variable naming.","severity":"deprecated","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Change app.use(websocket) to app.use(websocket())","cause":"Forgetting to call websocket() when using app.use.","error":"TypeError: websocket is not a function"},{"fix":"Run: npm install ws","cause":"ws peer dependency not installed.","error":"Error: Cannot find module 'ws'"},{"fix":"Upgrade to v2 and use await ctx.ws()","cause":"Using an older version where ctx.ws was the instance directly, but now it's a function.","error":"Error: ctx.ws is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}