| 1 | # xmpp.js |
| 2 | ## Server-side XMPP in Javascript |
| 3 | |
| 4 | [xmpp.js](http://xmppjs.prosody.im/) is a library for [Node.js](http://nodejs.org/) that allows |
| 5 | you to connect to an XMPP server as a component. |
| 6 | |
| 7 | For those already familiar with the client-side [Strophe.js](http://code.stanziq.com/strophe/) |
| 8 | library then there is almost nothing to learn - the API is almost exactly the same. The only |
| 9 | difference is that this time you can run your code on the server, and handle XMPP traffic from |
| 10 | clients on behalf of a whole domain. It's like writing an XMPP server but with the hard parts |
| 11 | handled for you. |
| 12 | |
| 13 | xmpp.js works with any [XEP-0114](http://www.xmpp.org/extensions/xep-0114.html)-compliant server |
| 14 | (that's practically all of them), so you need not worry about your code being tied in to a |
| 15 | particular server implementation. |
| 16 | |
| 17 | ### How it works at the XMPP level |
| 18 | XMPP components "bind" to a domain, usually a subdomain of the main XMPP service, such as |
| 19 | pubsub.example.org, or conference.example.org. All incoming stanzas addressed to that domain |
| 20 | (to='service.example.org') or to entities on that domain (to='user@service.example.org') will be |
| 21 | routed to your xmpp.js-based code. |
| 22 | |
| 23 | For outgoing stanzas your component is in full control. You can specify any 'from' address on |
| 24 | your stanzas, many servers don't even enforce that the originating domain of the stanza is the |
| 25 | component's domain, allowing you to send stanzas on behalf of any user on the server. |
| 26 | |
| 27 | ### Getting started |
| 28 | Firstly, you'll need Node installed if you haven't it already, this is fairly straightforward - |
| 29 | [instructions are here](http://nodejs.org/#build). xmpp.js is confirmed to work with version |
| 30 | 0.1.30 (2010.02.22). |
| 31 | |
| 32 | Check out the source xmpp.js code, from either the |
| 33 | [Mercurial repository](http://code.matthewwild.co.uk/xmppjs/) or |
| 34 | [Github project](http://github.com/mwild1/xmppjs). |
| 35 | |
| 36 | In the examples directory you will find an example component which echoes messages it receives |
| 37 | back to the sender. If you have a local [Prosody](http://prosody.im/) server installed then you |
| 38 | can simply add these lines to your Prosody config to make this example work: |
| 39 | |
| 40 | Component "echo.localhost" |
| 41 | component_secret = "hellohello" |
| 42 | |
| 43 | Ater restarting Prosody try running: |
| 44 | |
| 45 | node examples/echo.js |
| 46 | |
| 47 | Log into your Prosody with a client and send a message to anything@echo.localhost - you should |
| 48 | receive an instant response back - congratulations! |