Guide · Open source

How to use PeerJS: connect browsers with data and calls

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

PeerJS is a JavaScript library that wraps WebRTC, the browser technology for direct connections between users, in a simpler API. This guide shows you how to install it, create peers, send data and start audio or video calls between browsers. It is written for developers adding real-time features to a web app.

PeerJSpeers/peerjs · ★ 13.5k · MIT Install options & downloads

Quick start

1Install the package. Run npm install peerjs or yarn add peerjs in your project.
2Import Peer. Import the Peer class from the peerjs package in your code.
3Create a peer. Instantiate new Peer with an ID you choose, or without one to get a random ID.
4Connect to another peer. Call peer.connect with the other peer's ID and send data after the open event fires.
5Receive connections. Listen for the connection event and attach data handlers to the incoming connection.
6Start a call. Get local media with getUserMedia, then call peer.call with the remote ID and your stream.

Install PeerJS with npm or yarn

PeerJS is installed as a package. Run one of the commands below in your project folder. The README lists Node.js or a bundler such as Parcel or Webpack as prerequisites and does not specify versions.

Once installed, import the library in your code using the named Peer export.

npm install peerjs
yarn add peerjs
import { Peer } from "peerjs";

Create a peer with an ID

Each user in a PeerJS app is a peer identified by an ID. You can pick your own ID, or omit it to get a random one from the server.

Peers find each other through a PeerServer, which the README describes as a separate project.

Pass a string to choose your own ID.
Leave the ID out to receive a random ID from the server.

const peer = new Peer("pick-an-id");

Send data between two browsers

To exchange data, one peer calls connect with the other peer's ID and sends messages once the connection is open. The receiving peer listens for the connection event and then for data.

Data connections are the pattern to use for chat-style messages in the README's examples.

const conn = peer.connect("another-peers-id");
conn.on("open", () => {
  conn.send("hi!");
});

peer.on("connection", (conn) => {
  conn.on("data", (data) => {
    console.log(data);
  });
  conn.on("open", () => {
    conn.send("hello!");
  });
});

Start an audio or video call

For calls, the caller asks for local media with navigator.mediaDevices.getUserMedia, then calls the other peer's ID with the stream. The answering peer gets the call event, requests its own stream and answers. Each side listens for a stream event to show the remote media in a video element.

The README's examples report errors from getUserMedia with console.error, so handle that failure case in your own code.

Caller: peer.call with the remote ID and local stream.
Answerer: listen for the call event, then call answer with a stream.

navigator.mediaDevices.getUserMedia({ video: true, audio: true }, (stream) => {
  const call = peer.call("another-peers-id", stream);
  call.on("stream", (remoteStream) => {
    // Show stream in some <video> element.
  });
}, (err) => {
  console.error("Failed to get local stream", err);
});

Check browser support and run tests

PeerJS is tested by the project against recent Chrome, Edge, Firefox and Safari versions using BrowserStack. The README says it may work in older browsers but is not officially supported there. Firefox 102 or newer is required for CBOR and MessagePack support.

To run the project's test suite from a clone of the repository, use the npm test command.

Use the browser versions listed in the README's support table as your baseline.
Test your own app in the browsers your users run.

npm test

What people use it for

Real-time chat between two browser users
Sending data messages between peers in a web app
Simple video or audio calls inside a web app
Prototyping a peer connection between two browsers without building your own signaling layer

Frequently asked questions

Is PeerJS free to use?

PeerJS is released under the MIT licence, as stated in the project listing. Check the repository's licence file for the full terms before using it in a commercial product.

Do I need a server to use PeerJS?

The README says PeerJS needs a PeerServer to help peers find each other. PeerServer is a separate project, and the README links to it.

How do I install PeerJS?

Run npm install peerjs or yarn add peerjs in your project, then import Peer from peerjs. You need Node.js or a bundler such as Parcel or Webpack.

Which browsers does PeerJS support?

The README lists tested versions of Chrome, Edge, Firefox and Safari and says other or older browsers are not officially supported. Firefox 102 or newer is required for CBOR and MessagePack support.

Why do I see 'Critical dependency: the request of a dependency is an expression' in the console?

The README says this message occurs when you use PeerJS with Webpack, and it is not critical. It relates to a Parcel issue linked in the README.

How does PeerJS compare to simple-peer, Socket.IO or Trystero?

PeerJS is a WebRTC wrapper with a small API that handles peer IDs and data and media connections. simple-peer, Socket.IO and Trystero are comparable projects you can evaluate for your own signaling and connection needs.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

PeerJS suits web developers who want to add data exchange or simple audio and video calls between browsers with a small TypeScript-based API. It is not a finished app for non-coders, and the README does not promise connections across every network, so pick another option if you need guaranteed connectivity or support for very old browsers.

Install options & downloads