Registry / web-framework / koa-websocket

koa-websocket

JSON →
library7.0.0jsnpmunverified

koa-websocket is a lightweight wrapper designed to integrate WebSocket functionality into Koa applications, providing a middleware handler that is compatible with `koa-route`. It leverages the popular `ws` library for its core WebSocket implementation. The package is currently at version 7.0.0 and has seen regular updates, including dependency upgrades to address security concerns and support newer Node.js versions. Key features include support for both `ws://` and `wss://` protocols, the ability to pass custom WebSocket server options, and seamless integration with Koa's middleware pattern via `app.ws.use`. It differentiates itself by offering a `koa-route`-like approach to WebSocket routing within the Koa ecosystem, simplifying the handling of WebSocket connections and messages alongside traditional HTTP routes, providing a structured way to build WebSocket-enabled Koa applications.

npm install koa-websocket
INSTALL
IMPORT
SIG · KOA-WEBSOCKET
K
koa-websocket
web-frameworkjavascriptv7.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

websockify
import websockify from 'koa-websocket';
import { websockify } from 'koa-websocket'; // This is not a named export. const websockify = require('koa-websocket'); // Functional CommonJS syntax, but ESM is preferred in modern Koa projects.
The `websockify` function is the default export from `koa-websocket`. It extends a Koa application instance to add WebSocket capabilities. While CommonJS `require` is common in older Koa projects and examples, ESM `import` is recommended for new projects and aligns with modern Node.js practices.
Koa
import Koa from 'koa';
const Koa = require('koa');
Required to create the base Koa application instance that `koa-websocket` will extend.
route
import route from 'koa-route';
const route = require('koa-route');
Commonly used alongside `koa-websocket` for routing WebSocket connections, mimicking the `koa-route` pattern for HTTP routes. This is a separate, optional package.

This quickstart demonstrates setting up a Koa application that handles both HTTP and WebSocket requests using `koa-websocket` and `koa-route`. It includes global WebSocket middleware and a specific route for `/chat/:id` to manage and interact with client messages.

import Koa from 'koa'; import route from 'koa-route'; import websockify from 'koa-websocket'; // Create a new Koa application and extend it with WebSocket capabilities const app = websockify(new Koa()); // Basic HTTP middleware (optional, but shows coexistence) app.use(async (ctx, next) => { console.log(`HTTP Request: ${ctx.method} ${ctx.path}`); await next(); }); // Global WebSocket middleware for all connections app.ws.use(async (ctx, next) => { console.log(`New WebSocket connection established for path: ${ctx.path}`); // You can perform authentication or other setup here await next(ctx); // Pass context to the next WebSocket middleware or route }); // WebSocket route handler using koa-route app.ws.use(route.all('/chat/:id', (ctx) => { const roomId = ctx.params.id; console.log(`Client connected to chat room: ${roomId}`); // Send a welcome message to the newly connected client ctx.websocket.send(`Welcome to chat room ${roomId}!`); // Listen for messages from this client ctx.websocket.on('message', (message) => { console.log(`Message from client in room ${roomId}: ${message}`); // Echo the message back to the sender ctx.websocket.send(`Echo (${roomId}): ${message}`); }); // Handle client disconnection ctx.websocket.on('close', () => { console.log(`Client disconnected from chat room: ${roomId}`); }); // Handle WebSocket errors ctx.websocket.on('error', (err) => { console.error(`WebSocket error in room ${roomId}:`, err.message); }); })); // Start the server on an available port, defaulting to 3000 const PORT = process.env.PORT || 3000; app.listen(PORT, () => { console.log(`Server listening on http://localhost:${PORT} and ws://localhost:${PORT}`); console.log('Try connecting with a WebSocket client to ws://localhost:3000/chat/general'); });
Debug
Known issues
breakingVersion 7.0.0 upgraded the underlying `ws` library to version 8.5.0. This may introduce breaking changes or behavioral shifts from `ws` that could affect your existing WebSocket client or server logic. Always consult the `websockets/ws` release notes.
fix
Review the official `websockets/ws` GitHub releases for version 8.x for specific breaking changes. Thoroughly test your application, including client-side WebSocket interactions, after upgrading `koa-websocket`.
affects: >=7.0.0
breakingWith `koa-websocket` v6.0.0, the `ws` dependency was upgraded to 7.0.1, which dropped support for Node.js 6.x. Running on older Node.js versions will lead to errors.
fix
Upgrade your Node.js runtime environment to version 8.x or newer. For current releases of `koa-websocket`, Node.js 12+ is generally recommended.
affects: >=6.0.0
breaking`koa-websocket` versions 4.0.0 and above are built for Koa v2. If you are using Koa v1, you must explicitly install `koa-websocket@2` to maintain compatibility.
fix
For Koa v1 projects, install `npm install koa-websocket@2`. For Koa v2 and newer, use `npm install koa-websocket` to get the latest compatible version.
affects: >=4.0.0
gotchaWebSocket middleware must be registered using `app.ws.use(...)` and not `app.use(...)`. The `app.use` method is for standard HTTP middleware, while `app.ws.use` is specific to WebSocket connections.
fix
Ensure all functions intended to handle WebSocket connections or messages are passed to `app.ws.use`.
affects: >=2.0.0
gotchaWithin `app.ws.use` middleware or route handlers, the Koa context (`ctx`) is augmented with the active WebSocket connection at `ctx.websocket`. You must use `ctx.websocket` to interact with the client.
fix
To send data, use `ctx.websocket.send()`. To listen for client messages or connection events, use `ctx.websocket.on('message', ...)` or `ctx.websocket.on('close', ...)`, etc.
affects: >=2.0.0
gotchaTo enable `wss://` (secure WebSockets), you must provide `httpsOptions` as the third argument to the `websockify` function. Without these options, only `ws://` connections will be supported.
fix
Pass a valid `httpsOptions` object (containing `key`, `cert`, etc.) from your SSL certificate setup as `websockify(new Koa(), wsOptions, httpsOptions)`.
affects: >=4.1.0
Errors
Common errors & fixes
TypeError: app.ws.use is not a function
The Koa application instance was not correctly wrapped by the `websockify` function from `koa-websocket`.
fix
Ensure your Koa app is initialized by wrapping it: `const app = websockify(new Koa());`
Error: Cannot find module 'koa'
The `koa` package, which is a peer dependency in practice, has not been installed in your project.
fix
Install Koa: `npm install koa`.
WebSocket connection to 'ws://localhost:3000/some-path' failed: Error during WebSocket handshake: Unexpected response code: 404
The WebSocket client is trying to connect to a path for which no `app.ws.use` route handler is configured or the path is incorrect.
fix
Verify that your client's WebSocket URL matches an `app.ws.use(route.all('/your-path', ...))` handler defined in your server-side code. Check for typos in paths and ensure the handler is correctly registered.
Error: self-signed certificate in certificate chain (for wss:// connections)
When using `wss://` with a self-signed or otherwise untrusted SSL certificate, clients will typically reject the connection unless explicitly configured to trust the certificate.
fix
For production, use a trusted SSL certificate from a Certificate Authority (e.g., Let's Encrypt). For development, configure your client to ignore self-signed certificates if applicable (e.g., for Node.js clients, `process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0'`).
Upgrade
Version history
7.0.0latest on npm
Audit
Dependencies
wsrequiredCore WebSocket server implementation that koa-websocket wraps and depends on for all WebSocket protocol handling.
Agent activity
2 hits · last 30 days
node
2
Resources