nestjs-websocket

library0.1.3jsnpmunverified

A NestJS module that integrates the ws WebSocket client library, providing a decorator-based API for WebSocket connections. Version 0.1.3 is the latest stable release, with no recent updates since 2022. It uses ws under the hood and offers synchronous and asynchronous module configuration via forRoot and forRootAsync. Key differentiators: full NestJS DI integration, decorators like @OnOpen and @OnMessage, and support for both Express and Fastify platforms. Currently in maintenance mode.

messaging

npm install nestjs-websocket

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NESTJS-WEBSOCKET

nestjs-websocket

messagingjavascriptv0.1.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.

WebSocketModule

✓ import { WebSocketModule } from 'nestjs-websocket'

✗ const WebSocketModule = require('nestjs-websocket')

ESM module - use import, not require. The package ships TypeScript definitions.

WebSocketClient

✓ import { WebSocketClient } from 'nestjs-websocket'

✗ import { WebSocketClient } from 'nestjs-websocket/src'

Named import, not default. Do not import from subpaths.

InjectWebSocketProvider

✓ import { InjectWebSocketProvider } from 'nestjs-websocket'

✗ import { InjectWebSocketProvider } from '@nestjs/common'

Custom decorator provided by this package, not from @nestjs/common.

OnOpen

✓ import { OnOpen } from 'nestjs-websocket'

✗ import { OnGatewayConnection } from '@nestjs/websockets'

Use this package's decorator, not the one from @nestjs/websockets (for socket.io).

Shows how to configure WebSocketModule, inject WebSocketClient, and use @OnOpen/@OnMessage decorators in a NestJS service.

import { Module } from '@nestjs/common'; import { WebSocketModule, WebSocketClient, InjectWebSocketProvider, OnOpen, OnMessage } from 'nestjs-websocket'; @Module({ imports: [ WebSocketModule.forRoot({ url: 'ws://localhost:3000', }), ], providers: [MyService], }) export class AppModule {} @Injectable() export class MyService { constructor( @InjectWebSocketProvider() private readonly ws: WebSocketClient, ) {} @OnOpen() onOpen() { console.log('Connection opened'); } @OnMessage() onMessage(data: any) { console.log('Received:', data); } sendMessage(msg: string) { this.ws.send(msg); } }

Debug

Known issues

gotchaThe module uses the 'ws' library's WebSocket, not the browser's native WebSocket. In Node.js environments, you may need to handle binary data differently.

fix

Use ws' API for binary data (e.g., Buffer). Avoid assuming browser webSocket behavior.

affects: all

deprecatedPackage is in maintenance mode - no updates since 2022. Future NestJS versions (>=9) may have compatibility issues.

fix

Consider using built-in @nestjs/websockets or migrate to a more active alternative like '@nestjs/platform-ws'.

affects: >=0.1.3

gotchaThe @InjectWebSocketProvider() decorator must be used on a property, not in constructor. The README example shows constructor injection but the decorator is property-based.

fix

Use it as property decorator: @InjectWebSocketProvider() private ws: WebSocketClient;

affects: all

breakingBreaking change in v0.1.0: The method to access WebSocket instance changed from 'getWebSocket()' to direct property 'ws' after injection.

fix

If upgrading from older versions, change your code to use the injected instance directly.

affects: <0.1.0

Errors

Common errors & fixes

Cannot find module 'nestjs-websocket' or its corresponding type declarations.

Package not installed or missing TypeScript types.

fix

Run 'npm install nestjs-websocket' and ensure tsconfig.json includes 'node_modules' in types or has 'skipLibCheck: false'.

Error: The 'url' option is required for WebSocketModule.forRoot()

Missing required 'url' parameter in configuration.

fix

Add a valid WebSocket URL to the options object, e.g., { url: 'ws://localhost:3000' }.

TypeError: this.ws.send is not a function

Injected WebSocketClient property is not initialized (likely using constructor injection incorrectly).

fix

Use property decorator: @InjectWebSocketProvider() private ws: WebSocketClient;

Upgrade

Version history

0.1.3latest on npm

Audit

Dependencies

@nestjs/commonoptionalPeer dependency for NestJS module decorators and DI

wsrequiredCore WebSocket client implementation

Agent activity

21 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/blockcoders/nestjs-websocket ↗

packagenestjs-websocket ↗

homepagehttps://github.com/blockcoders/nestjs-websocket/blob/main/README.md ↗