{"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,"search_vec":"'4.14.0':35 'abstract':84 'activ':46 'applic':59 'auto':73 'auto-detect':72 'bi':43 'bi-month':42 'bot':23,110 'build':20 'charact':75 'client':29 'complet':79 'complianc':64 'comprehens':10 'connect':92 'current':31 'design':15 'detect':74 'develop':47 'differenti':61 'driven':102 'easi':52 'emphas':49 'encod':76 'event':101 'event-driven':100 'fledg':27 'framework':2,7,14,83 'frequent':37 'full':26 'full-fledg':25 'handl':88,105 'includ':62 'indic':45 'irc':1,6,13,22,28,86,106,109 'irc-framework':5 'ircv3':66 'javascript':108 'key':60 'larger':58 'lightweight':51 'manag':94 'messag':107,111 'model':103 'month':40,44 'multipl':70,89 'node.js':4,17 'perform':12 'pong':96 'protocol':87 'provid':98 'releas':38 'rough':39 'scalabl':56 'server':91,95 'simultan':90 'specif':67 'stabl':32 'suit':81 'suitabl':18 'support':68 'test':80 'transpar':93 'use':54 'version':33","created_at":"2026-04-20T01:54:01.039447+00:00","updated_at":"2026-04-20T01:54:01.039447+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/kiwiirc/irc-framework","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/irc-framework","openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication","http-networking","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}