# PeerJS — Simple Peer-to-Peer Communication with WebRTC

> PeerJS wraps the WebRTC API into a simple interface for building peer-to-peer data and media connections in the browser, with an optional self-hosted signaling server.

## Install

Save in your project root:

# PeerJS — Simple Peer-to-Peer Communication with WebRTC

## Quick Use
```bash
# Install the client library
npm install peerjs

# Self-host the signaling server
npm install peer
npx peerjs --port 9000
```

```javascript
// Browser: create a peer and connect
import { Peer } from "peerjs";

const peer = new Peer("my-id");
peer.on("open", (id) => console.log("My peer ID:", id));

// Connect to another peer
const conn = peer.connect("other-id");
conn.on("open", () => conn.send("Hello!"));
```

## Introduction
WebRTC enables direct browser-to-browser communication but its API is complex, involving ICE candidates, SDP negotiation, and STUN/TURN servers. PeerJS abstracts all of this into a few function calls. You create a peer, connect by ID, and send data or stream media without touching the underlying protocol.

## What PeerJS Does
- Provides a high-level JavaScript API for WebRTC data channels and media streams
- Handles all signaling, ICE negotiation, and connection setup automatically
- Includes a self-hostable signaling server (PeerServer) for connection brokering
- Supports reliable and unreliable data channels for different use cases
- Works in all modern browsers that support WebRTC (Chrome, Firefox, Safari, Edge)

## Architecture Overview
PeerJS consists of two parts: the client library and PeerServer. The client library wraps the browser's RTCPeerConnection API, managing SDP offer/answer exchange and ICE candidate gathering. PeerServer is a lightweight Node.js WebSocket server that acts as a signaling relay — it helps peers find each other and exchange connection metadata, but no user data flows through it. Once peers connect, all communication is direct browser-to-browser.

## Self-Hosting & Configuration
- Install `peerjs` (client) via npm or include via CDN for browser usage
- Self-host PeerServer with `npm install peer && npx peerjs --port 9000`
- Deploy PeerServer as a Docker container or on any Node.js hosting platform
- Configure STUN/TURN servers via the `config.iceServers` option for NAT traversal
- Set `debug` levels (0-3) on the client for troubleshooting connection issues

## Key Features
- Minimal API: create a Peer, call `connect()` for data or `call()` for media in just a few lines
- Self-hostable signaling server with zero external dependencies
- Supports binary data transfer (ArrayBuffer, Blob) alongside text
- Automatic reconnection handling when peers temporarily disconnect
- TypeScript definitions included for type-safe development

## Comparison with Similar Tools
- **Socket.IO** — server-relayed WebSocket communication; PeerJS is true peer-to-peer with no data flowing through the server
- **simple-peer** — lower-level WebRTC wrapper without a signaling server; PeerJS includes PeerServer out of the box
- **Livekit** — production video infrastructure with SFU; PeerJS is lighter and mesh-based for small groups
- **WebTorrent** — uses WebRTC for P2P file sharing via the BitTorrent protocol; PeerJS is a general-purpose data/media library
- **Trystero** — serverless WebRTC using MQTT or other transports for signaling; PeerJS uses its own signaling server

## FAQ
**Q: Does data flow through the PeerServer?**
A: No. PeerServer only handles signaling (helping peers discover each other). Once connected, all data and media flow directly between browsers.

**Q: How many peers can connect simultaneously?**
A: PeerJS uses a mesh topology, so each peer connects to every other peer. This works well for small groups (under 10-15 peers). For larger groups, consider an SFU-based solution.

**Q: Do I need a TURN server?**
A: STUN servers (free, e.g., Google's) handle most NAT traversal. TURN servers are needed when both peers are behind strict symmetric NATs, which occurs in roughly 10-15% of connections.

**Q: Can I use PeerJS for video calls?**
A: Yes. Use `peer.call(peerId, mediaStream)` to initiate a media call. PeerJS handles the WebRTC negotiation for audio and video streams.

## Sources
- https://github.com/peers/peerjs
- https://peerjs.com/docs

---
Source: https://tokrepo.com/en/workflows/asset-cc81edba
Author: AI Open Source