irc

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 19 Open GitHub ↗

IRC client protocol module for Deno, Node.js and Bun

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# irc

![ci](https://github.com/jeromeludmann/irc/workflows/ci/badge.svg)
[![JSR](https://jsr.io/badges/@irc/client)](https://jsr.io/@irc/client)
[![npm](https://img.shields.io/npm/v/irc-client-ts)](https://www.npmjs.com/package/irc-client-ts)
![Deno 2+](https://img.shields.io/badge/Deno-2%2B-000?logo=deno)
![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933?logo=nodedotjs&logoColor=white)
![Bun 1+](https://img.shields.io/badge/Bun-1%2B-f472b6?logo=bun&logoColor=white)

IRC client protocol module for [Deno](https://deno.land/) 2+,
[Node.js](https://nodejs.org/) 20+ and [Bun](https://bun.sh/) 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](https://jsr.io/@irc/client) and [npm](https://www.npmjs.com/package/irc-client-ts).

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

## Documentation

- [Getting Started](#getting-started)
- [API Reference](https://github.com/jeromeludmann/irc/blob/main/API.md)

## Getting Started

### Installation

**Deno:**

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

**Node.js:**

```sh
npm add irc-client-ts
```

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

**Bun:**

```sh
bun add irc-client-ts
```

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

### Usage

Instantiate a new client like this:

```ts
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](https://github.com/jeromeludmann/irc/blob/main/API.md#options) to learn more about available options.

Then you can listen to [events](#events) and send [commands](#commands):

```ts
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:

```ts
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:

```ts
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.

```ts
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:

```ts
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:

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

See [API Reference](https://github.com/jeromeludmann/irc/blob/main/API.md#events) to learn more about events.

### Commands

Commands are the way to send messages to the server.

They can be sent by just calling them:

```ts
client.join("#channel");

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

client.quit("Goodbye!");
```

See [API Reference](https://github.com/jeromeludmann/irc/blob/main/API.md#commands) 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](https://github.com/jeromeludmann/irc/blob/main/API.md#event-error) to learn more about errors.

## Contributors

See [CONTRIBUTING.md](https://github.com/jeromeludmann/irc/blob/main/CONTRIBUTING.md) to get started.

## License

[MIT](LICENSE)

irc

Today's picks

Was this content helpful?

Recent Feedback

irc

Today's picks

Was this content helpful?

Recent Feedback

Download README