fastify-ws

library1.0.3jsnpmunverified

Basic WebSocket support for Fastify built on the ws and uws libraries. Current stable version is 1.0.3, with infrequent releases. It provides a simple plugin to add WebSocket functionality to Fastify, exposing a `fastify.ws` WebSocket.Server instance. Supports both `ws` (default) and `uws` backends, but `uws` is abandoned. Differentiator: minimal plugin for legacy Fastify versions, but not actively maintained and lacks full lifecycle management compared to @fastify/websocket.

devops

npm install fastify-ws

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FASTIFY-WS

fastify-ws

devopsjavascriptv1.0.3

harness data pending

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.

default

✓ import fastifyWs from 'fastify-ws'

✗ const fastifyWs = require('fastify-ws')

ESM default import; CommonJS require is also valid but not recommended for TypeScript.

fastify.ws

✓ fastify.register(fastifyWs) const wss = fastify.ws

✗ const wss = fastify.websocket

After registration, the WebSocket.Server instance is attached to `fastify.ws`. Do not use `fastify.websocket`.

connection

✓ fastify.ws.on('connection', (socket) => { ... })

✗ fastify.ws.on('connect', (socket) => { ... })

Event name is 'connection', not 'connect'. 'socket' is the WebSocket instance.

Registers fastify-ws plugin, waits for ready, then adds an echo WebSocket server.

const fastify = require('fastify')() fastify.register(require('fastify-ws')) fastify.ready(err => { if (err) throw err fastify.ws.on('connection', socket => { socket.on('message', msg => socket.send(msg)) }) }) fastify.listen({ port: 3000 }, (err, address) => { if (err) throw err console.log(`Server listening on ${address}`) })

Debug

Known issues

deprecatedThis package is not actively maintained. Consider using @fastify/websocket instead.

fix

Use @fastify/websocket which is the official Fastify WebSocket plugin.

affects: *

gotchaThe uws backend is abandoned and may have security vulnerabilities. Default is ws.

fix

Do not configure uws; stick with default ws backend.

affects: *

breakingMust call fastify.ready() before accessing fastify.ws or the server will not start.

fix

Call fastify.ready() or await fastify.ready() before using fastify.ws.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read property 'on' of undefined

Accessing fastify.ws before registering the plugin or before fastify.ready() is called.

fix

Ensure fastify.register(require('fastify-ws')) is called and then await fastify.ready() before accessing fastify.ws.

ERR_MODULE_NOT_FOUND: Cannot find module 'fastify-ws'

Using import syntax without proper ESM configuration or missing .mjs extension.

fix

Use import fastifyWs from 'fastify-ws' inside a "type": "module" package or use require().

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

fastifyrequiredPeer dependency; must be installed alongside fastify-ws.

wsoptionalDefault WebSocket implementation; used unless uws is configured.

uwsoptionalOptional alternative WebSocket backend; abandoned.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/gj/fastify-ws ↗

packagefastify-ws ↗

homepagehttps://github.com/gj/fastify-ws#readme ↗