{"id":13345,"library":"irc-framework","title":"IRC Framework for Node.js","description":"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.","status":"active","version":"4.14.0","language":"javascript","source_language":"en","source_url":"https://github.com/kiwiirc/irc-framework","tags":["javascript","IRC","bot","messaging"],"install":[{"cmd":"npm install irc-framework","lang":"bash","label":"npm"},{"cmd":"yarn add irc-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add irc-framework","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import IRC from 'irc-framework';","symbol":"IRC Module (CJS)","correct":"const IRC = require('irc-framework');\nconst bot = new IRC.Client();"},{"note":"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`.","wrong":"import { Client } from 'irc-framework';","symbol":"IRC Module (ESM)","correct":"import IRC from 'irc-framework';\nconst bot = new IRC.Client();"},{"note":"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.","symbol":"Client Class Type","correct":"import type { Client } from 'irc-framework';"}],"quickstart":{"code":"import IRC from 'irc-framework';\n\nconst bot = new IRC.Client();\nbot.connect({\n\thost: 'irc.freenode.net',\n\tport: 6667,\n\tnick: 'prawnsbot'\n});\n\nbot.on('message', function(event) {\n  \tif (event.message.indexOf('hello') === 0) {\n  \t\t  event.reply('Hi!');\n  \t}\n  \t\n  \tif (event.message.match(/^!join /)) {\n  \t\tvar to_join = event.message.split(' ')[1];\n  \t\tevent.reply('Joining ' + to_join + '..');\n  \t\tbot.join(to_join);\n  \t}\n});\n\n// Or a quicker way to match messages...\nbot.matchMessage(/^hi/, function(event) {\n\tevent.reply('hello there!');\n});","lang":"javascript","description":"This quickstart demonstrates how to create an IRC bot, connect to a server, and respond to messages with basic commands like 'hello' and '!join'."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 14 or newer.","message":"Node.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.","severity":"breaking","affected_versions":">=4.13.0"},{"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.","message":"The 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.","severity":"breaking","affected_versions":">=4.10.0"},{"fix":"Implement a custom `on('ctcp request', ...)` handler to respond to `CLIENTINFO` if your application requires it.","message":"As 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.","severity":"breaking","affected_versions":">=4.9.0"},{"fix":"Verify SOCKS configuration and potentially update related dependencies if experiencing connection issues.","message":"SOCKS 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.","severity":"gotcha","affected_versions":">=4.11.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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)","cause":"The client attempted to connect or rejoin a channel/server from which it is banned.","error":"ERR_YOUREBANNEDCREEP event triggered"},{"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.","cause":"The SASL authentication mechanism is not correctly detected or negotiated with the IRC server, often due to an issue with 'capability_missing' detection logic.","error":"SASL authentication fails with 'capability_missing' detection"},{"fix":"Upgrade to `irc-framework@4.12.0` or newer, which includes a fix for `user.host` not being set during connection.","cause":"A bug in older versions prevented `user.host` and potentially other user-specific information from being correctly populated after establishing a connection.","error":"User's host or other info not set during connection"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}