PeerJS docs

Get started with PeerJS

PeerJS requires two components: the PeerJS client library and the PeerServer.

PeerServer

The PeerServer brokers connections between PeerJS clients. Once two clients have established a connection with each other with the PeerServer's help, data is will flow between the clients directly.

Choose one of the following options:

Sign up for free cloud-hosted PeerServer service

Alternatively, PeerServer is available on GitHub and on npm:

npm install peer

Setting up the server on your own is just a few lines of code:

var PeerServer = require('peer').PeerServer;
      var server = new PeerServer({ port: 9000 });

PeerJS Client

The client is where all the action is at.

1. Include the PeerJS client in your frontend Javascript code:

<script src="http://cdn.peerjs.com/0/peer.min.js"></script>
      

2. Create the Peer object.

You'll need to provide an ID. When other peers try to connect to you, they'll have to know this ID.

Also you'll need to provide either the API key for your PeerServer cloud account or your own PeerServer:

var peer = new Peer('some-id', {key: 'myapikey'});
      

Or if you're running your own PeerServer

var peer = new Peer('some-id', {host: 'localhost', port: 9000});
      

3. That's it! You're ready to send and receive binary P2P data connections!

Listening for incoming connections:

peer.on('connection', function(conn){
        conn.on('data', function(data) {
          console.log('Got data:', data);
        });
      });
      

Create a peer connection:

var conn = peer.connect('some-id');
      conn.on('open', function() {
        conn.send('Hello world!');
      });
      

Other cool things you need to know

What kind of data can I send?

PeerJS has the BinaryPack serialization format built-in. This means you can send any JSON type as well as binary Blobs and ArrayBuffers. You don't have to worry about serializing yourself. Simple put objects in on one side and get objects out on the other:

conn.send({
          strings: 'hi!',
          numbers: 150,
          arrays: [1,2,3],
          evenbinary: new Blob([1,2,3]),
          andmore: {bool: true}
        });
        

With BinaryPack, the data is never converted to strings. Everything is binary end-to-end. This results in bandwidth savings.

Preconnection

When you try to connect to a peer, PeerServer will hold a connection offer for up to 5 seconds before rejecting it. This is useful if you want to reconnect to a peer as it disconnects and reconnects rapidly between web pages.

Connection latency/bandwidth

Data sent between the two peers do not touch any other servers, so the connection speed is limited only by the upload and download rates of the two peers. This also means you don't have the additional latency of an intermediary server.

The latency to establish a connection is identified by two factors: the brokering of data and identifying of clients. PeerJS has been carefully coded to minimize latency in both applications. Data is brokered through an XHR streaming request before a WebSocket connection is established, then through WebSocket afterwards. Identity is self-provided and thus a new client can report identity, accept an outstanding offer, and and provide answer and thus establish the peer-to-peer connection in very few RTTs.

Note that in the infrequent case that both peers are behind symmetric NATs, this is no longer true. See below.

Peer-to-peer shortingcomings

A very low percentage of users are behind symmetric NATs. When two symmetric NAT users try to connect to each other, NAT traversal is impossible and no connection can be made. A workaround is to proxy through what is known as a TURN server. The PeerServer cloud service does not provide a TURN server. You'll have to find your own. You can pass a TURN server into the Peer object options. This will allow your PeerJS app to work seamlessly for this situation

Current state of browser compatibility

Detailed browser compatibility information

Discuss PeerJS on our Google Group