Skip to content
Branch: master
Find file History
Latest commit feb8cec Jun 15, 2019


An XMPP client is an entity that connects to an XMPP server.

@xmpp/client package includes a minimal set of features to connect and authenticate securely and reliably.

It supports Node.js, browser and React Native. See below for differences.


npm install @xmpp/client or yarn add @xmpp/client


const {client, xml, jid} = require('@xmpp/client')



Replace VERSION with the desired version number.

const {client, xml, jid} = window.XMPP


const {client, xml} = require('@xmpp/client')

const xmpp = client({
  service: 'ws://localhost:5280/xmpp-websocket',
  domain: 'localhost',
  resource: 'example',
  username: 'username',
  password: 'password',

xmpp.on('error', err => {
  console.error('', err.toString())

xmpp.on('offline', () => {
  console.log('', 'offline')

xmpp.on('stanza', async stanza => {
  if ('message')) {
    await xmpp.send(xml('presence', {type: 'unavailable'}))
    await xmpp.stop()

xmpp.on('online', async address => {
  console.log('', 'online as', address.toString())

  // Makes itself available
  await xmpp.send(xml('presence'))

  // Sends a chat message to itself
  const message = xml(
    {type: 'chat', to: address},
    xml('body', 'hello world')
  await xmpp.send(message)

// Debug
xmpp.on('status', status => {
  console.debug('🛈', 'status', status)
xmpp.on('input', input => {
  console.debug('', input)
xmpp.on('output', output => {
  console.debug('', output)



See xml package


See jid package


  • options <Object>

    • service <string> The service to connect to, accepts an URI or a domain.
      • domain lookup and connect to the most secure endpoint using @xmpp/resolve
      • xmpp://hostname:port plain TCP, may be upgraded to TLS by @xmpp/starttls
      • xmpps://hostname:port direct TLS
      • ws://hostname:port/path plain WebSocket
      • wss://hostname:port/path secure WebSocket
    • domain <string> Optional domain of the service, if omitted will use the hostname from service. Useful when the service domain is different than the service hostname.
    • resource <string> Optional resource for resource binding
    • username <string> Optional username for sasl
    • password <string> Optional password for sasl

Returns an xmpp object.


xmpp is an instance of EventEmitter.


online indicates that xmpp is authenticated and addressable. It is emitted every time there is a successfull (re)connection.

offline indicates that xmpp disconnected and no automatic attempt to reconnect will happen (after calling xmpp.stop()).

Additional status:

  • connecting: Socket is connecting
  • connect: Socket is connected
  • opening: Stream is opening
  • open: Stream is open
  • closing: Stream is closing
  • close: Stream is closed
  • disconnecting: Socket is disconnecting
  • disconnect: Socket is disconnected

You can read the current status using the status property.

const isOnline = xmpp.status === 'online'

You can listen for status change using the status event.

Event status

Emitted when the status changes.

xmpp.on('status', status => {

Event error

Emitted when an error occurs. For connection errors, xmpp will reconnect on its own using @xmpp/reconnect however a listener MUST be attached to avoid uncaught exceptions.

  • <Error>
xmpp.on('error', error => {

Event stanza

Emitted when a stanza is received and parsed.

// Simple echo bot example
xmpp.on('stanza', stanza => {
  if (!'message')) return

  const message = stanza.clone() = stanza.attrs.from

Event online

Emitted when connected, authenticated and ready to receive/send stanzas.

xmpp.on('online', address => {
  console.log('online as', address.toString())

Event offline

Emitted when the connection is closed an no further attempt to reconnect will happen, after calling xmpp.stop().

xmpp.on('offline', () => {


Starts the connection. Attempts to reconnect will automatically happen if it cannot connect or gets disconnected.

xmpp.on('online', address => {
  console.log('online', address.toString())

Returns a promise that resolves if the first attempt succeed or rejects if the first attempt fails.


Stops the connection and prevent any further auto reconnect/retry.

xmpp.on('offline', () => {

Returns a promise that resolves once the stream closes and the socket disconnects.


Sends a stanza.


Returns a promise that resolves once the stanza is serialized and written to the socket or rejects if any of those fails.


See @xmpp/reconnect.


XMPP supports multiple transports, this table list @xmpp/client supported and unsupported transport for each environment.

transport protocols Node.js Browser React Native
WebSocket ws://, wss://
TCP xmpp://
TLS xmpps://


Multiple authentication mechanisms are supported. PLAIN should only be used over secure WebSocket (wss://), direct TLS (xmpps:) or a TCP (xmpp:) connection upgraded to TLS via STARTTLS

SASL Node.js Browser React Native
  • ☐ : Optional
  • ✗ : Unavailable
  • ✔ : Included

Common issues

Unable to resolve module

If you are using an older React Native version, please require/import @xmpp/client/reat-native instead of @xmpp/client.

You can’t perform that action at this time.