Registry / messaging / lavalink-ws-client

lavalink-ws-client

library1.1.2jsnpmunverified

Type-safe WebSocket client for Lavalink v4 Beta 3. Current stable version is 1.1.2, released on an ongoing schedule via GitHub. It leverages the lavalink-protocol package for type definitions and requires lavalink-api-client as a peer dependency. Provides a lightweight and performant abstraction over raw WebSocket connections with full TypeScript support. Differentiators include strict typing, minimal overhead, and compatibility with the latest Lavalink beta protocol.

messaging

npm install lavalink-ws-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LAVALINK-WS-CLIENT

lavalink-ws-client

messagingjavascriptv1.1.2

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.

LavalinkWS

✓ import { LavalinkWS } from 'lavalink-ws-client';

✗ const LavalinkWS = require('lavalink-ws-client');

ESM-only package; CommonJS require is not supported. Node.js >=20 required.

WebSocketClientOptions

✓ import { WebSocketClientOptions } from 'lavalink-ws-client';

✗ import { WebSocketClientOptions } from 'lavalink-ws-client/types';

Types are re-exported from the main entry; no subpath imports needed.

default

✓ import LavalinkWS from 'lavalink-ws-client';

✗ import { default as LavalinkWS } from 'lavalink-ws-client';

Default export is available and preferred for the main class.

Creates a Lavalink WebSocket client instance, connects to the server, and sends a voice update.

import { LavalinkWS } from 'lavalink-ws-client'; import { Node } from 'lavalink-protocol'; const ws = new LavalinkWS({ host: 'localhost', port: 2333, password: process.env.LAVALINK_PASSWORD ?? 'youshallnotpass', secure: false, userId: '123456789', shardCount: 1, }); ws.on('open', () => { console.log('Connected to Lavalink'); }); ws.on('error', (err) => { console.error('WebSocket error:', err); }); ws.on('close', (code, reason) => { console.log('Disconnected:', code, reason); }); // Example: sending a voice server update ws.send({ op: 'voiceUpdate', guildId: '123456789', sessionId: 'abc', event: { token: 'tok', endpoint: 'endpoint', }, });

Debug

Known issues

gotchaPackage is ESM-only and requires Node.js >=20. Using CommonJS require will fail.

fix

Ensure your project uses ESM ("type": "module" in package.json or .mjs files) and Node.js 20+.

affects: >=1.0

gotchaPeer dependencies must be installed manually: lavalink-api-client and lavalink-protocol. Missing them causes runtime errors.

fix

Install peer dependencies: npm install lavalink-api-client lavalink-protocol

affects: >=1.0

deprecatedThe 'secure' option in WebSocketClientOptions may be deprecated in future versions in favor of a unified 'tls' option.

fix

Use 'tls: { rejectUnauthorized: false }' instead of 'secure: false' if available.

affects: <=1.1.2

breakingIn v1.0.0, the constructor signature changed from (options: WSOptions) to (options: WebSocketClientOptions). Old code with WSOptions will break.

fix

Update to use WebSocketClientOptions interface. Refer to the changelog.

affects: <1.0.0

gotchaThe 'send' method expects a Lavalink protocol message object. Passing raw strings will fail.

fix

Always send objects conforming to lavalink-protocol types. Use the provided send overloads.

affects: >=1.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module

Using CommonJS require() on an ESM-only package.

fix

Switch to ESM imports or use dynamic import().

TypeError: lavalink_ws_client_1.LavalinkWS is not a constructor

Incorrect import syntax, likely mixing default and named imports.

fix

Use `import { LavalinkWS } from 'lavalink-ws-client'` or `import LavalinkWS from 'lavalink-ws-client'` consistently.

Cannot find module 'lavalink-protocol'

Missing peer dependency lavalink-protocol.

fix

Run `npm install lavalink-protocol` in your project.

Property 'send' does not exist on type 'LavalinkWS'

Using an outdated TypeScript definition or wrong import.

fix

Update package to latest version and ensure type imports are correct.

Upgrade

Version history

1.1.2latest on npm

Audit

Dependencies

lavalink-api-clientrequiredpeer dependency for API client integration

lavalink-protocolrequiredpeer dependency for protocol types and constants

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubssh://git@github.com/lavaclient/lavaclient ↗

packagelavalink-ws-client ↗

homepagehttps://lavaclient.js.org ↗