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

npm install tinyws

github ↗package ↗

INSTALL

IMPORT

SIG · TINYWS

tinyws

http-networkingjavascriptv1.0.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.

tinyws

✓ import { tinyws } from 'tinyws'

✗ const tinyws = require('tinyws')

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

TinyWSRequest

✓ import { TinyWSRequest } from 'tinyws'

✗ import type { TinyWSRequest } from 'tinyws'

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

App

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

✗ import { App } from 'express'

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

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 issues

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.

fix

Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`). For mixed CJS/ESM projects, use `import()` within an `async` function: `const { tinyws } = await import('tinyws');`

affects: >=1.0.0

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.

fix

Run `npm install ws` or `pnpm i ws` in your project directory.

affects: >=1.0.0

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.

fix

Follow the pattern `const server = app.listen(PORT); tinyws(app, server);` ensuring both `app` and the raw `http.Server` instance are provided.

affects: >=1.0.0

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.

fix

Always use `if (req.ws) { const ws = await req.ws(); /* ... */ }` within your route handler to properly establish and interact with the WebSocket.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'ws' imported from tinyws

The `ws` package, a peer dependency, has not been installed.

fix

Run `npm install ws` or `pnpm i ws` to add the required WebSocket library.

TypeError: Cannot read properties of undefined (reading 'ws')

The `tinyws` middleware was not correctly initialized with your application and HTTP server, or the request path does not match a configured WebSocket path.

fix

Ensure `tinyws(app, server, { paths: '/your-ws-path' });` is called after your HTTP server is created, and that the client is connecting to one of the specified `paths`.

TypeError: req.ws is not a function

The `tinyws` middleware might be applied but `req.ws` is not correctly typed or the `req.ws` property is not being awaited.

fix

Ensure your `Request` type is augmented with `TinyWSRequest` (e.g., `App<Request & TinyWSRequest>`) and that you `await req.ws()` to get the WebSocket instance.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

wsrequiredCore WebSocket library that tinyws builds upon; required for functionality.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

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

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