Registry / http-networking / koa-easy-ws

koa-easy-ws

library2.1.0jsnpmunverified

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.

http-networking web-framework

npm install koa-easy-ws

github ↗package ↗

INSTALL

IMPORT

SIG · KOA-EASY-WS

koa-easy-ws

http-networkingjavascriptv2.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

websocket

✓ import websocket from 'koa-easy-ws'

✗ const websocket = require('koa-easy-ws')

ES module import, default export.

websocket() call

✓ app.use(websocket())

✗ app.use(websocket)

Must call as a function to configure middleware.

websocket.server

✓ const wsServer = websocket().server

Access the underlying ws server instance for advanced configuration.

Shows basic setup: import, middleware registration, WebSocket handling with ctx.ws, and fallback HTTP response.

import Koa from 'koa'; import websocket from 'koa-easy-ws'; const app = new Koa(); app.use(websocket()); app.use(async (ctx) => { if (ctx.ws) { const ws = await ctx.ws(); ws.send('hello from koa-easy-ws'); } else { ctx.body = 'HTTP response'; } }); app.listen(3000);

Debug

Known issues

breakingIn version 2.x, ctx.ws is now a function returning a Promise, not a ws instance directly.

fix

Use await ctx.ws() to get the ws instance.

affects: >=2.0.0

gotchaMust install ws and koa as peer dependencies manually.

fix

Run: npm install ws koa

affects: >=1.0.0

gotchaMiddleware must be called as a function (websocket()) not just referenced.

fix

Use app.use(websocket())

affects: >=1.0.0

deprecatedThe default export name 'websocket' may be confused with the 'ws' library; use clear variable naming.

fix

Use import easyWs from 'koa-easy-ws' or const { default: easyWs } = require('koa-easy-ws')

affects: all

Errors

Common errors & fixes

TypeError: websocket is not a function

Forgetting to call websocket() when using app.use.

fix

Change app.use(websocket) to app.use(websocket())

Error: Cannot find module 'ws'

ws peer dependency not installed.

fix

Run: npm install ws

Error: ctx.ws is not a function

Using an older version where ctx.ws was the instance directly, but now it's a function.

fix

Upgrade to v2 and use await ctx.ws()

Upgrade

Version history

2.1.0latest on npm

Audit

Dependencies

wsrequiredPeer dependency for WebSocket server

koarequiredPeer dependency, Koa framework

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/b3nsn0w/koa-easy-ws ↗

packagehttps://www.npmjs.com/package/koa-easy-ws ↗