IRC client logic using irc-protocol for communication


Basic IRC client using irc-protocol.

irc-client makes your life easier if you're implementing anything that acts as an IRC client by providing some common base functionality. Much of this functionality is exposed using events like message:private or channel:join. Read on through the API section for more information.

It's expected that one would extend the Client "class" and add their own features on top. To that end, the core features of irc-client will remain quite minimal.

Available via npm:

$ npm install irc-client

Or via git:

$ npm install git://


Constructs a new client object with the supplied options.

new Client([options]);
// basic instantiation 
var client = new Client({
  server: {
    host: "",
    port: 6667,
  nickname: "example",
  username: "irc-client",
  realname: "example client",
  channels: [
    ["#example", "password-for-example"],


  • options - an object containing parameters used to instantiate the client.


  • server - an object with host and optionally port parameters. The default is {host: "", port: 6667}.
  • nickname - a string containing the nickname for the client.
  • username - a string containing the username for the client.
  • realname - a string containing the "real name" for the client.
  • channels - an array containing channels to join upon connection to the server. If an entry is a string, it will be joined with no password, but if it is an array, it will be treated as [channel, password] and joined as such.


Joins a channel, optionally calling a callback with a possible error value when complete.

client.join(channel, [password], [cb]);
client.join("#example", "example-password", function(err) {
  if (err) {
    console.log("couldn't join #example: " + err);
  } else {
    console.log("joined #example");


  • channel - a channel name. Easy.
  • password - the password for the channel. Optional.
  • cb - a callback that will be called, possibly with an error, when either the channel is joined, or an error happens. If there is no error, the first argument will be null. Also optional.


Leaves a channel.

client.part(channel, reason);
client.part("#example", "going to sleep");


  • channel - the name of a channel that you should be currently in. The effects are undefined if you're not already in that channel.
  • reason - the "reason" for parting the channel. Don't look back in anger.


Sends a message (using PRIVMSG) to a particular target.

client.say(to, text);
client.say("#channel", "good news, everyone");
// OR 
client.say("friend", "hi, friend");


  • to - the target of the message. Can be anything that a PRIVMSG will work against. This is kind of defined by the server.
  • text - the content of the message. Can't contain newlines or anything else that the server doesn't approve of.


Sends a CTCP-style message to a particular target. Mostly a convenience wrapper around .say().

client.ctcp(to, text);
client.ctcp("friend", "TIME");


(see say() above)


Sends a NOTICE message to a particular target.

client.notice(to, text);
client.notice("friend", "i'm disconnecting");


(see say() above);

Also see example.js.

var net = require("net");
var Client = require("irc-client");
var Greeter = function Greeter() {
  Client.apply(this, arguments);
  this.regexes_private = [];
  this.regexes_public = [];
  this.on("message:public", function(fromtomessage) {
    this.regexes_public.filter(function(regex) {
      var matches;
      if (matches = regex[0].exec(message)) {
        regex[1](from, to, message, matches);
  this.on("message:private", function(fromtomessage) {
    this.regexes_private.filter(function(regex) {
      var matches;
      if (matches = regex[0].exec(message)) {
        regex[1](from, to, message, matches);
  this.transfers = [];
Greeter.prototype = Object.create(Client.prototype, {properties: {constructor: Greeter}});
Greeter.prototype.match_private = function match_private(regexcb) {
  this.regexes_private.push([regex, cb]);
Greeter.prototype.match_public = function match_public(regexcb) {
  this.regexes_public.push([regex, cb]);
Greeter.prototype.match = function match(regexcb) {
  this.match_private(regex, cb);
  this.match_public(regex, cb);
var greeter = new Greeter({
  server: {host: "", port: 6667},
  channels: ["#channel"],
greeter.on("irc", function(message) {
greeter.match(/^(hey|hi|hello)/i, function(fromtomessagematches) {
  var target = to;
  if (target.toLowerCase() === greeter.nickname.toLowerCase()) {
    target = from;
  greeter.say(target, "no, " + matches[1] + " to YOU, " + from.nick);

3-clause BSD. A copy is included with the source.