TypeScript icon, indicating that this package has built-in type declarations

5.0.0-rc.3 • Public • Published

A lightweight and powerful lavalink v4 client for NodeJs.

  • Easy-to-use: lavaclient has a neat and user-friendly promise-based api.
  • Performant: designed to be small and lightweight, it's a great choice for any project.
  • Library Agnostic: lavaclient doesn't require you to use a specific discord library. Use anything you want!


Node.js LTS (or higher) is required to use lavaclient.


(p)npm install lavaclient
// or
yarn add lavaclient

Beta (may be outdated)

(p)npm install lavaclient@next
// or
yarn add lavaclient@next


Take a look at lavadeno :)



import { Cluster, Node, type NodeOptions } from "lavaclient";

const info: NodeOptions["info"] = {
    host: "",
    port: 2333,
    auth: "youshallnotpass"

// If you only have a single lavalink node, use the `Node` class.
const lavaclient = new Node({
    ws: {
        // The client name to use, defaults to some very long string lol.
        clientName: "my very cool bot",
        // Resuming is enabled by default, but you can disable it if you want.
        // The timeout defaults to 1 minute.
        resuming: false | { timeout: 30_000 },
        // The reconnecting options, this is enabled by default.
        // If you want to disable it, set it to `false`.
        reconnecting: {
            // The number of tries to reconnect before giving up, defaults to Infinity.
            tries: 3,
            // The delay in milliseconds between each attempt, defaults to 5 seconds.
            // This can either be a function that accepts the current try and returns the delay, or a static delay.
            delay: (attempt) => attempt * 1_000
    rest: {
        // Whether lavalink should return stack traces for requests that ran into exceptions.
        enableTrace: true,
        // The fetch implementation to use, defaults to node.js built-in fetch.
        fetch: fetch,
        // The user agent to use for requests, defaults to some very long string lol.
        userAgent: "my very cool bot (v1.0.0, <user id>)"
    discord: {
        sendGatewayCommand: (id, payload) => // Send the payload to the Discord Gateway.

// If you have multiple lavalink nodes, use the `Cluster` class.
const lavaclient = new Cluster({
    // An array of lavalink node options, this supports the same thing as the `Node` class.
    nodes: [{ info }],
    discord: {
        sendGatewayCommand: (id, payload) => // Send the payload to the Discord Gateway.

// Connect to the lavalink node(s).
await lavaclient.connect("1077037369850605599");

Using Players


const player = lavaclient.players.create("<guild id>");


// Passing `true` as the 2nd arg will skip checking if the player exists locally.
await lavaclient.players.destroy("<guild id>", true);

If you want a player to leave the voice channel, you can do this first:


Playing Tracks

import { S, getUserData } from "lavaclient";

const results = await lavaclient.api.loadTracks("ytsearch:never gonna give you up");
if (results.loadType === "search") {
    const track =[0];

    // You can pass a track object directly.

    // If you want to pass some user data to the track, you can do this:
        encoded: track.encoded,
        userData: { requesterId: },

    // There's also an option to pass a user data schema for type-safe user data values.
    const schema = S.struct({
        requesterId: S.string,

        encoded: track.encoded,
        userData: { requesterId: },
        userDataSchema: schema,

    getUserData(player.track, schema); // { requesterId: string }



player.setFilters({ volume: 0.5 });
player.setFilters("volume", 0.5);;

// A little experimental but you can transfer a player to a different node.

Handling Voice Updates

Lavalink requires you to forward voice server & state updates to it so that it can connect to the voice channel.

Here's a discord.js v14 example:

import { Client, GatewayDispatchEvents } from "discord.js";

const client = new Client({ ... });,  (u) => lavaclient.players.handleVoiceUpdate(u));, (u) => lavaclient.players.handleVoiceUpdate(u));

Support Server

Dependencies (6)

Dev Dependencies (6)

Package Sidebar


npm i lavaclient

Weekly Downloads






Unpacked Size

107 kB

Total Files


Last publish


  • the2dperson