Minimal IRC connection that simply emits event objects. Plugin modules can do the rest.


Ok, enough with the giant modules that provide more features than you need for a simple bot.

This module gives you the minimal IRC connection and simply emits event objects. It only includes what it takes to connect and stay connected.

Plugin modules can (and should) do the rest.

Now you can whip up a lightweight bot without all the baggage.

Channel support can be added with the irc-channels module!

npm install irc-connect
var irc = require("irc-connect");
var ircOptions = {
    //[port] if not provided defaults to 6667 (or if secure, 6697) 
    port: 6667,
    //[secure] can be true/false or 'semi' for lazy CA checking (self-signed, obscure CA, etc) 
    secure: false,
    //[nick] is the desired nickname, if not provided one will be generated (you can always use nick() later) 
    nick: 'WernerB',
    //[realname] is the "real name" shown in WHOIS results 
    realname: 'Werner Brandes',
    //[ident] is the user part of your hostmask (before the @), if not provided 'irc-cnct' will be used 
    // note this may either be prefixed with a ~ on some servers, if you don't have an 'identd' service 
    // if you do have such a service, most servers will use what is obtained there and ignore this 
    ident: 'wbrandes'
var freenode = irc.connect('', ircOptions)
    //include some plugins 
    .use(irc.pong, irc.names, irc.motd)
    //fires when the servers sends the welcome message (RPL_WELCOME) 
    .on('welcome', function (msg) {
        this.nick('pokey', 'pa$$word', function(err){
            console.log('There was a problem setting your NICK:', err);
    //fires after the server confirms password 
    .on('identified', function (nick) {
        this.send('JOIN #node.js');
    //fires only when YOUR nick changes 
    .on('nick', function (nick) {
        console.log('Your nick is now:', nick);
    .on('NOTICE', function (event) {
        console.log('NOTICE:', event.params[1]);
    .on('JOIN', function (event) {
        console.log(event.nick, 'joined');
    .on('PRIVMSG', function (event) {
        var params = event.params;
        console.log('message from: '+event.nick, 'to: '+params[0], params[1]);
    //from the `names` plugin. 
    .on('names', function (cnamenames) {
        console.log(cname, names);
    //from the `motd` plugin. 
    .on('motd', function (event) {

All data from the server is parsed and emitted using the data's command as the event name. Numeric events (as defined by RFC 1459) are converted to their string codes. The full list can be viewed in the irc-replies module.

All events follow this distinct pattern:

  • UPPERCASE events are direct IRC events. They are always passed the parsed event object.
  • lowercase events are custom events from irc-connect or a pluggin.

These are directly from the underlying socket connection.

This module uses Visionmedia's debug module.

Show everything:

$ DEBUG=irc:connect* node app.js

Show only connect/disconnect messages

$ DEBUG=irc:connect node app.js

Show raw incoming data:

$ DEBUG=irc:connect-raw node app.js

Show parsed incoming data as JSON:

$ DEBUG=irc:connect-parsed node app.js

Show outgoing data:

$ DEBUG=irc:connect-out node app.js

As mentioned above, this module's goal is to allow plugins to be added that provide richer features.

Plugins can export a __irc function for use to call. The function will be passed a reference to the connection. The plugin should wire any listeners needed and augment it with helper functions/properties needed.

IRC does a PING - PONG game to verify the client is still alive. Use this plugin to automatically reply to the server's PINGs and stay connected.

Parses replies from a NAMES command and emits a names event with the results as an object.

Parses replies from a MOTD command and emits a motd event with the results as an object.

Sets a NICK with an optional password and a error callback. This only works properly if your server has a NickServ or similar service which requires a password to register your nick, and sends a success NOTICE. On a vanilla ircd you may need to send your own NICK command, the events will still work the same.

Emitted anytime your nick is changed.