tinyws

library1.0.0jsnpmunverified

tinyws is a lightweight, framework-agnostic WebSocket middleware for Node.js, built upon the popular `ws` library. It enables WebSocket capabilities for HTTP servers, integrating seamlessly with frameworks like tinyhttp, Express, and Polka by exposing a `req.ws()` method. The current stable version is 1.0.0, as of April 2026. This package distinguishes itself from alternatives like `express-ws` by being actively maintained, providing first-class TypeScript support, being pure ESM, and boasting a minimal footprint (under 500B). Its primary release cadence appears to be focused on stability and maintenance rather than rapid feature additions, making it a reliable choice for adding WebSockets to modern Node.js applications.

http-networking web-framework

github ↗package ↗

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.

tinyws is an ESM-only package. Direct CommonJS `require` is not supported. Use dynamic import for CJS contexts.

import { tinyws } from 'tinyws'

While `import type` is valid for types, `TinyWSRequest` is also exported as a value for convenience; both forms are compatible in TypeScript.

import { TinyWSRequest } from 'tinyws'

The quickstart example uses `@tinyhttp/app`. If using Express, substitute `express` and its `Request` type accordingly.

import { App, Request } from '@tinyhttp/app'

This quickstart initializes a tinyhttp server with tinyws, creating a WebSocket endpoint at `/ws` that echoes messages back to the client. It demonstrates how to access the WebSocket instance via `req.ws()` and handle basic messaging.

import { App, Request } from '@tinyhttp/app'; import { tinyws, TinyWSRequest } from 'tinyws'; import { WebSocket } from 'ws'; // For type inference if needed const app = new App<Request & TinyWSRequest>(); app.use('/ws', async (req, res) => { if (req.ws) { const ws: WebSocket = await req.ws(); ws.on('message', (message) => { console.log(`Received: ${message}`); ws.send(`Echo: ${message}`); }); ws.on('close', () => console.log('WebSocket closed.')); ws.send('Hello from tinyws server!'); } else { res.send('Hello from HTTP endpoint! This is not a WebSocket connection.'); } }); const server = app.listen(3000, () => { console.log('HTTP/WebSocket server listening on port 3000'); }); tinyws(app, server, { paths: '/ws' }); // To test, run: // node -e "const WebSocket = require('ws'); const ws = new WebSocket('ws://localhost:3000/ws'); ws.onopen = () => ws.send('Test message'); ws.onmessage = (event) => console.log(event.data);"

Debug

Known footguns

breakingtinyws is a pure ESM package. Applications that are strictly CommonJS (CJS) will need to convert to ESM or use dynamic `import()` for tinyws to function correctly. Direct `require()` calls will result in an error.

gotchaIt is crucial to install the `ws` package alongside `tinyws`, as `ws` is a peer dependency and not bundled. Forgetting `ws` will lead to runtime errors when tinyws attempts to use it.

gotchaWhen integrating `tinyws` with an HTTP server, ensure the `tinyws` initialization function is called *after* the HTTP server is created and passed the `app` instance and the `server` object. Calling it too early or with incorrect arguments will prevent WebSocket upgrades from functioning.

gotchaUnlike some other middleware, `tinyws` exposes the WebSocket functionality via a `req.ws()` *function* that returns a Promise for the WebSocket instance. Developers must `await` this call and check for `req.ws`'s existence to correctly handle WebSocket connections.

Upgrade

Version history

Breaking-change detection hasn't run for this library yet.

Audit

Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity

0 hits · last 30 days

No traffic data recorded yet.

Resources

githubhttps://github.com/tinyhttp/tinyws ↗

packagehttps://www.npmjs.com/package/tinyws ↗