Registry / communication / irc-framework

irc-framework

library4.14.0jsnpmunverified

irc-framework is a comprehensive and performant IRC framework designed for Node.js, suitable for building both IRC bots and full-fledged IRC clients. The current stable version is 4.14.0, with frequent releases (roughly monthly to bi-monthly) indicating active development. It emphasizes being lightweight, easy to use, and scalable for larger applications. Key differentiators include its compliance with IRCv3 specifications, support for multiple and auto-detected character encodings, and a complete test suite. The framework abstracts the IRC protocol, handles multiple simultaneous server connections, transparently manages server PONGing, and provides an event-driven model for handling IRC messages.

communication http-networking web-framework

npm install irc-framework

github ↗package ↗

INSTALL

IMPORT

SIG · IRC-FRAMEWORK

irc-framework

communicationjavascriptv4.14.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

IRC Module (CJS)

✓ const IRC = require('irc-framework'); const bot = new IRC.Client();

✗ import IRC from 'irc-framework';

For CommonJS environments, the library exports an object named `IRC` which contains the `Client` class. Attempting to use ESM `import` syntax will result in a syntax error or unexpected behavior in CJS-only environments.

IRC Module (ESM)

✓ import IRC from 'irc-framework'; const bot = new IRC.Client();

✗ import { Client } from 'irc-framework';

When using ESM, the library's primary export is a default object named `IRC` which encapsulates the `Client` class. Direct named imports for `Client` are not typically supported and may result in an undefined `Client`.

Client Class Type

✓ import type { Client } from 'irc-framework';

For TypeScript projects, the `Client` class type can be imported directly to provide type annotations for client instances without importing the runtime value. This is useful for strict type checking.

This quickstart demonstrates how to create an IRC bot, connect to a server, and respond to messages with basic commands like 'hello' and '!join'.

import IRC from 'irc-framework'; const bot = new IRC.Client(); bot.connect({ host: 'irc.freenode.net', port: 6667, nick: 'prawnsbot' }); bot.on('message', function(event) { if (event.message.indexOf('hello') === 0) { event.reply('Hi!'); } if (event.message.match(/^!join /)) { var to_join = event.message.split(' ')[1]; event.reply('Joining ' + to_join + '..'); bot.join(to_join); } }); // Or a quicker way to match messages... bot.matchMessage(/^hi/, function(event) { event.reply('hello there!'); });

Debug

Known issues

breakingNode.js v12 is no longer supported since version 4.13.0 due to dependencies dropping support for it. Users on Node.js v12 or older must upgrade their Node.js environment to a supported version.

fix

Upgrade your Node.js runtime to version 14 or newer.

affects: >=4.13.0

breakingThe framework no longer emits empty or malformed IRC messages through standard event handlers since version 4.10.0. While these messages are still available via the `raw` event, logic that depended on receiving and handling malformed messages through higher-level events will break.

fix

Review message parsing and handling logic. If you need to process malformed raw IRC data, subscribe to the `raw` event instead of `message` or other parsed events.

affects: >=4.10.0

breakingAs of version 4.9.0, `irc-framework` no longer replies to `CLIENTINFO` CTCP requests. Bots or clients that rely on automatic replies to `CLIENTINFO` will need to implement custom handling if this functionality is still required.

fix

Implement a custom `on('ctcp request', ...)` handler to respond to `CLIENTINFO` if your application requires it.

affects: >=4.9.0

gotchaSOCKS support was moved to a more maintained external package in v4.11.0 to address timeouts. While this improves stability, ensure your SOCKS configuration is compatible with the new underlying implementation if you encounter issues.

fix

Verify SOCKS configuration and potentially update related dependencies if experiencing connection issues.

affects: >=4.11.0

Errors

Common errors & fixes

ERR_YOUREBANNEDCREEP event triggered

The client attempted to connect or rejoin a channel/server from which it is banned.

fix

Implement an event handler for `irc error: 'banned'` or similar to gracefully handle bans, inform the user, or attempt to reconnect with different credentials/IP if appropriate. (Introduced in v4.10.0)

SASL authentication fails with 'capability_missing' detection

The SASL authentication mechanism is not correctly detected or negotiated with the IRC server, often due to an issue with 'capability_missing' detection logic.

fix

Ensure your server supports the chosen SASL mechanism. If on an affected version (pre-4.13.1), upgrading to `irc-framework@4.13.1` or newer may resolve internal detection issues.

User's host or other info not set during connection

A bug in older versions prevented `user.host` and potentially other user-specific information from being correctly populated after establishing a connection.

fix

Upgrade to `irc-framework@4.12.0` or newer, which includes a fix for `user.host` not being set during connection.

Upgrade

Version history

4.14.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/kiwiirc/irc-framework ↗

packagehttps://www.npmjs.com/package/irc-framework ↗