irc

IRC client protocol module for Deno 2+, Node.js 20+ and Bun 1+ which aims to provide an easy way to talk with IRC servers.

• Cross-runtime — runs on Deno, Node.js and Bun with the same API
• Fully typed — events, commands and state are inferred from TypeScript, no guessing
• Plugin architecture — 50+ built-in plugins (SASL, DCC, CTCP, reconnect, flood control...)
• IRCv3 — server-time, echo-message, message-tags, MONITOR, SASL, and more
• Zero dependencies — no external runtime dependencies

Any feedback and contributions are welcome.

Available on JSR and npm.

Originally built for Deno as deno-irc, now also compatible with Node.js and Bun.

Documentation

• Getting Started
• API Reference

Getting Started

Installation

Deno:

import { Client } from "jsr:@irc/client";

Node.js:

npm add irc-client-ts

import { Client } from "irc-client-ts";

Bun:

bun add irc-client-ts

import { Client } from "irc-client-ts";

Usage

Instantiate a new client like this:

const client = new Client({
  nick: "my_nick",
  channels: ["#my_channel"],
});

One instance manages one connection. If you want to connect to many servers, use many instances.

See API Reference to learn more about available options.

Then you can listen to events and send commands:

client.on("join", (msg) => {
  if (msg.params.channel === "#my_channel") {
    client.privmsg("#my_channel", "Hello world!");
  }
});

Finally you have to establish a connection with the server:

await client.connect("irc.libera.chat");

await client.connect("irc.libera.chat", { port: 6697, tls: true });

When using Deno, connecting to servers requires the --allow-net permission:

deno run --allow-net ./code.ts

Events

Events are simple messages which are emitted from the client instance.

They can be received by listening to their event names:

client.on("join", (msg) => {
  const { source, params } = msg;
  console.log(`${source?.name} has joined ${params.channel}`);
});

Thanks to TypeScript, type of msg is always inferred from the event name so you do not have to worry about what is in the object or about the IRC protocol.

client.on("nick", ({ source, params }) => {
  console.log(`${source?.name} is now known as ${params.nick}`);
});

client.on("privmsg", ({ source, params }) => {
  console.log(`${source?.name} on ${params.target} says ${params.text}`);
});

Some events, like "privmsg" and "notice", can be filtered like this:

client.on("privmsg:channel", ({ source, params }) => {
  console.log(`${source?.name} on ${params.target} says ${params.text}`);
});

client.on("notice:private", ({ source, params }) => {
  console.log(`${source?.name} notices to you: ${params.text}`);
});

Subscribing to more than one event is also possible by passing an array of event names:

client.on(["part", "kick"], (msg) => {
  // msg is PartEvent | KickEvent
});

See API Reference to learn more about events.

Commands

Commands are the way to send messages to the server.

They can be sent by just calling them:

client.join("#channel");

client.privmsg("#channel", "Hello world!");

client.quit("Goodbye!");

See API Reference to learn more about commands.

Errors

When an error is emitted, it will be thrown by default and causes a crash of the program.

To avoid the client from crashing, it is required to have at least one event listener for the "error" event name.

See API Reference to learn more about errors.

Contributors

See CONTRIBUTING.md to get started.

License

MIT