Build A Phone With PeerJS

Introduction

Creating a real-time voice or video communication application used to require significant expertise in WebRTC, the complex underlying technology for peer-to-peer communication in browsers. WebRTC involves managing ICE candidates, signaling servers, and intricate connection negotiation that can overwhelm even experienced developers. PeerJS emerges as a powerful abstraction layer that simplifies these complexities, allowing developers to focus on building communication features rather than wrestling with protocol details.

In this comprehensive guide, you'll discover how to build a fully functional internet-connected phone application using PeerJS. We'll walk through everything from setting up your development environment to implementing call initiation, answer handling, and proper cleanup procedures. By the end of this tutorial, you'll have a working phone application that can connect users across different browsers and devices using peer-to-peer communication.

What You'll Learn

This tutorial covers the complete implementation of a browser-based phone application. You'll gain hands-on experience with the PeerJS client library and server components, understanding how they work together to facilitate peer-to-peer connections. We explore the getUserMedia API for accessing user microphones and cameras, the Peer object lifecycle for managing connections, and the event-driven patterns that handle incoming calls gracefully.

Beyond the basics, we examine production-ready considerations including TURN server configuration for users behind restrictive firewalls, error handling strategies for various connection failure scenarios, and cleanup procedures that prevent resource leaks. These advanced topics ensure your phone application performs reliably across diverse network conditions and user environments. For teams building real-time communication features as part of larger web application projects, mastering these concepts provides a foundation for integrating voice and video capabilities seamlessly.

Prerequisites

Before diving into the implementation, ensure you're comfortable with several foundational technologies that form the backbone of this project. This is an intermediate-level tutorial that assumes familiarity with core web development concepts and server-side JavaScript.

Required Knowledge

Successful completion of this tutorial requires working knowledge of vanilla JavaScript, including ES6+ features like arrow functions, promises, and async/await patterns that appear throughout the PeerJS API. You should understand how to manipulate the DOM, work with browser APIs, and handle events effectively.

Node.js proficiency is essential since we'll create a server to handle peer brokering and signaling. Familiarity with Express.js helps, though the server code we implement remains straightforward and well-documented. Understanding of HTML fundamentals including form elements, buttons, and video/audio elements ensures you can build the user interface for your phone application.

Development Environment Setup

Begin by installing Node.js from the official website if you haven't already. The Node package manager (npm) comes bundled with Node and handles dependency management throughout the project. Many developers prefer Yarn as an alternative package manager, and while our examples use Yarn syntax, you can substitute equivalent npm commands if preferred.

Create a new project directory and initialize it with your chosen package manager. Install the required dependencies including PeerJS for the client-side library and Express for serving your application locally. Consider adding nodemon for development convenience, which automatically restarts your server when files change during development.

# Initialize project with Yarn
yarn init -y

# Install dependencies
yarn add peerjs express

# Install development dependency
yarn add --dev nodemon

Understanding PeerJS Architecture

PeerJS consists of two interconnected components that work together to enable peer-to-peer communication. The client-side library provides a clean JavaScript API for creating connections and managing calls, while the PeerServer handles the initial brokering of connections between peers. Understanding how these components interact is crucial for building reliable communication applications.

The PeerJS Client Library

The client library is what developers interact with directly in their applications. It wraps the browser's native WebRTC implementation, abstracting away the complex ICE (Interactive Connectivity Establishment) negotiation and signaling processes. When you create a Peer object, the library handles the creation of WebRTCPeerConnection instances, manages ICE candidate exchange, and provides convenient event hooks for connection lifecycle events.

The library supports both data connections for arbitrary data transfer and media connections for audio and video streams. Data connections use WebRTC's DataChannel API, supporting various serialization formats including binary, JSON, and plain text. Media connections leverage WebRTC's RTP (Real-time Transport Protocol) capabilities for transmitting audio and video between peers with minimal latency.

Each peer receives a unique identifier that other peers use to establish connections. By default, PeerJS generates random IDs, but you can specify custom IDs if your application requires specific addressing schemes. These IDs serve only for connection brokering--the actual peer-to-peer data transfer occurs directly between clients after the initial handshake.

The PeerServer Component

PeerServer acts as the signaling server for WebRTC connections, facilitating the initial discovery and connection establishment between peers. When two peers want to communicate, they first connect to the signaling server, which helps them exchange connection information and ICE candidates. Once the direct peer-to-peer connection is established, the signaling server is no longer involved in the communication.

PeerJS provides a cloud-hosted PeerServer that you can use without any setup, making it ideal for development and small-scale deployments. For production applications or environments with specific requirements, you can run your own PeerServer instance. Self-hosting gives you control over server configuration, allows customization of ID generation policies, and eliminates dependence on external services.

The signaling server handles several critical functions: assigning peer IDs when none are provided, brokering connection offers and answers between peers, and facilitating ICE candidate exchange. It maintains a registry of connected peers and routes signaling messages appropriately. Understanding these responsibilities helps you diagnose connection issues and optimize your application's behavior.

Setting Up the Development Environment

With a solid understanding of PeerJS architecture, we can now set up the development environment. This section walks through creating the project structure, installing dependencies, and configuring the server to support our phone application.

Creating the Project Structure

Begin by creating a new directory for your phone application project. Inside this directory, establish a clear folder structure that separates client-side and server-side code. A typical structure includes a public folder for static assets that the browser will load, an index.js file for your server code, and optionally a server.js file for production server configuration.

The public folder should contain your HTML file, client-side JavaScript, and any CSS stylesheets. Organize these assets logically--consider separate folders for JavaScript modules, stylesheets, and images if your application requires them. This structure scales well as your application grows and makes it easier to locate and maintain code.

Installing Dependencies

Initialize your project with npm or Yarn to create a package.json file that tracks dependencies and project metadata. Install PeerJS as a client-side dependency--while you'll load this via a script tag in the HTML, having it in package.json helps with version management. Install Express to serve your application and handle static file delivery.

For development convenience, consider installing nodemon as a development dependency. Nodemon watches your files for changes and automatically restarts the server, eliminating manual restart cycles during development. This significantly improves the development experience, especially when making frequent changes to server code.

Configuring the Server

Create an Express server that serves your static files and optionally hosts a PeerServer instance. The server configuration remains relatively simple--set up Express to serve files from the public directory, configure middleware for parsing requests if needed, and define routes for any API endpoints your application requires.

// index.js - Server configuration
const express = require('express');
const http = require('http');
const { ExpressPeerServer } = require('peerjs');
const path = require('path');

const app = express();
const server = http.createServer(app);

// Create PeerJS server
const peerServer = ExpressPeerServer(server, {
 debug: true,
 path: '/peerjs'
});

// Use PeerJS server
app.use('/peerjs', peerServer);

// Serve static files
app.use(express.static(path.join(__dirname, 'public')));

// Start server
server.listen(3000, () => {
 console.log('Server running on http://localhost:3000');
});

For the PeerJS server component, you have two options: use the cloud-hosted service or run a local instance. During development, the cloud service offers the simplest setup--you don't need to configure anything beyond the default client configuration. For production or testing behind firewalls, you'll want to run a local PeerServer and configure clients to connect to your local instance.

Creating the Peer Object

The Peer object serves as the foundation for all peer-to-peer communication in your application. This section explores how to create, configure, and initialize the Peer object, preparing it for connections and calls.

Constructor Options

The Peer constructor accepts optional parameters for customization. The first parameter is a peer ID--a string that uniquely identifies this peer on the network. If you omit this parameter, PeerJS assigns a random ID through the brokering server. Custom IDs must start and end with alphanumeric characters and can contain dashes and underscores in the middle.

The second parameter is an options object that controls various aspects of Peer behavior. Key options include the host and port for specifying a custom PeerServer location, path for the server route, and secure for HTTPS connections. The config option accepts an object containing ICE server configuration--typically STUN and TURN servers that assist with NAT traversal.

The debug option controls logging verbosity, accepting values from 0 (no logs) to 3 (all logs). During development, setting debug to 2 or 3 helps diagnose connection issues by showing signaling messages and ICE candidate exchange. In production, set debug to 0 to reduce console noise and improve performance.

Initialization and Events

When you create a Peer instance, it begins connecting to the signaling server asynchronously. The 'open' event fires when the connection is established and the peer has received its ID. At this point, the peer can receive incoming connections and initiate outgoing ones. You should not wait for this event before allowing other operations, as messages to the server queue automatically until the connection is ready.

Listen for the 'connection' event to handle incoming data connection requests from other peers. The event callback receives a DataConnection object representing the new connection. Similarly, listen for the 'call' event to handle incoming media calls--this callback receives a MediaConnection object that you must answer explicitly to establish the connection.

The 'error' event is critical for robust applications. PeerJS groups errors by type, including 'browser-incompatible' for unsupported browsers, 'peer-unavailable' when connecting to non-existent peers, and various network-related errors. Handle these errors gracefully to provide feedback to users and attempt recovery when appropriate.

// Create a peer with custom configuration
const peer = new Peer('my-phone-app-user-123', {
 host: '/', // Use relative host for local server
 port: '3000',
 path: '/peerjs',
 secure: false,
 debug: 2,
 config: {
 iceServers: [
 { urls: 'stun:stun.l.google.com:19302' },
 { urls: 'stun:stun1.l.google.com:19302' }
 ]
 }
});

// Handle successful connection to signaling server
peer.on('open', (id) => {
 console.log('My peer ID is: ' + id);
 updateStatus('Ready to make calls');
});

// Handle incoming data connections
peer.on('connection', (conn) => {
 console.log('Incoming connection from: ' + conn.peer);
 setupDataConnection(conn);
});

// Handle incoming calls
peer.on('call', (call) => {
 console.log('Incoming call from: ' + call.peer);
 handleIncomingCall(call);
});

// Handle errors
peer.on('error', (err) => {
 console.error('Peer error:', err.type, err);
 handlePeerError(err);
});

Accessing the Microphone

Before your phone application can transmit audio, it must obtain permission to access the user's microphone. The getUserMedia API provides this capability, requesting user consent and delivering media streams that connect to PeerJS calls.

Requesting Media Permissions

The getUserMedia method accepts a constraints object specifying the types of media to request. For a voice-only phone application, request audio track without video. The browser displays a permission prompt, and users must explicitly allow access for the application to proceed. Handle the permission denial gracefully, explaining to users why microphone access is necessary and providing alternative ways to use the application.

The constraints object supports various options for audio configuration. You can specify echo cancellation, noise suppression, and auto gain control preferences. These processing options help improve call quality by reducing background noise and preventing audio clipping. The exact available options vary by browser, so implement fallbacks for unsupported constraints.

Creating a Media Stream

When the user grants permission, getUserMedia returns a MediaStream object containing audio tracks. This stream can be displayed locally using an audio element with the muted attribute for feedback, or passed directly to PeerJS for transmission to remote peers. Keep a reference to the local stream so you can stop it when calls end.

// Request microphone access
async function initializeMedia() {
 try {
 const stream = await navigator.mediaDevices.getUserMedia({
 audio: {
 echoCancellation: true,
 noiseSuppression: true,
 autoGainControl: true
 },
 video: false // Audio-only for this tutorial
 });

 localStream = stream;
 updateStatus('Microphone connected');
 return stream;
 } catch (error) {
 console.error('Error accessing microphone:', error);
 handleMediaError(error);
 return null;
 }
}

Making Calls

With the Peer object initialized and microphone access granted, you can now implement the core phone functionality: making calls to other peers. This section covers initiating outgoing calls and handling the various states during connection establishment.

Initiating an Outgoing Call

To call another peer, use the peer.call() method with the destination peer's ID and your local media stream. The method returns a MediaConnection object that represents the pending call. Attach event listeners to this object to track connection progress and handle the remote peer's stream when it arrives.

The call event provides the remote peer's media stream through its 'stream' event. Attach this stream to an audio element to hear the remote caller. The stream event may fire at different times depending on network conditions--wait for it before assuming the call is fully established.

Managing Call State

Track the call state using the MediaConnection object's properties and events. The open property indicates when the call is fully established and bidirectional communication is possible. The 'close' event fires when the call ends, either through normal hangup or connection failure.

// Initiate an outgoing call
function callPeer(peerId) {
 if (!localStream) {
 console.error('No local media stream available');
 return;
 }

 // Create the call
 const call = peer.call(peerId, localStream);

 // Track this call
 currentCall = call;

 // Handle remote stream
 call.on('stream', (remoteStream) => {
 console.log('Remote stream received');
 playRemoteStream(remoteStream);
 });

 // Handle call opening
 call.on('open', () => {
 console.log('Call connected');
 updateCallStatus('Connected');
 });

 // Handle call errors
 call.on('error', (err) => {
 console.error('Call error:', err);
 handleCallError(err);
 });

 // Handle call ending
 call.on('close', () => {
 console.log('Call ended');
 endCall();
 });

 updateCallStatus('Calling...');
}

Answering Calls

When another peer initiates a call, your application must handle the incoming call event and answer appropriately. This section explores the call answering workflow and considerations for providing a complete calling experience.

Handling Incoming Calls

The 'call' event fires when a remote peer attempts to connect. The event callback receives a MediaConnection object representing the incoming call. Unlike data connections where the connection is established automatically, media calls require explicit answering--you must call the answer() method on the MediaConnection to accept the call.

When answering, you can provide your local media stream to enable two-way audio. If you call answer() without arguments, a one-way call is established where the caller can send audio but cannot receive anything from you. For a complete phone experience, always provide your local stream when answering.

Answer Code Example

// Handle incoming calls
function handleIncomingCall(call) {
 // Check if already on another call
 if (currentCall && currentCall.open) {
 // Handle busy state - reject or ignore
 console.log('Already on a call, ignoring incoming');
 return;
 }

 // Store the incoming call
 currentCall = call;

 // Answer the call with our local stream
 call.answer(localStream);

 // Handle remote stream
 call.on('stream', (remoteStream) => {
 console.log('Incoming call connected, playing remote audio');
 playRemoteStream(remoteStream);
 });

 // Handle call open
 call.on('open', () => {
 console.log('Incoming call answered');
 updateCallStatus('Connected');
 });

 // Handle call close
 call.on('close', () => {
 console.log('Incoming call ended');
 endCall();
 });

 updateCallStatus('Incoming call...');
}

Ending Calls

Proper call termination is essential for a complete phone application experience. This section covers graceful call ending, resource cleanup, and UI updates that signal call completion to users.

Closing Connections

To end a call, call the close() method on the MediaConnection object. This initiates the WebRTC hangup process, sending termination signals to the remote peer and releasing resources. After calling close(), the 'close' event fires when the connection fully terminates, providing a reliable signal for cleanup operations.

Beyond closing the media connection, stop all local media tracks to release microphone access. The MediaStream's getTracks() method returns all tracks, and calling stop() on each releases the hardware resource. This is important both for privacy (ensuring the microphone is off after calls) and for system performance (freeing audio processing resources).

Cleanup and Resource Management

Implement a comprehensive cleanup routine that handles all resources when calls end. Reset UI elements to their idle state, clear any references to streams and connections, and update status displays to reflect the ready state. Properly cleaned resources prevent memory leaks and ensure the application remains responsive during extended use.

// End the current call
function endCall() {
 if (currentCall) {
 // Close the media connection
 currentCall.close();
 currentCall = null;
 }

 // Stop local audio tracks
 if (localStream) {
 localStream.getTracks().forEach(track => track.stop());
 localStream = null;
 }

 // Clear remote audio
 const remoteAudio = document.getElementById('remoteAudio');
 if (remoteAudio) {
 remoteAudio.srcObject = null;
 }

 // Update UI
 updateCallStatus('Call ended');
 updateStatus('Ready');
}

Handling Errors and Edge Cases

Robust error handling distinguishes a professional phone application from a basic proof-of-concept. This section covers common error scenarios and strategies for maintaining application stability under adverse conditions.

Common Error Types

PeerJS categorizes errors by type, helping you implement targeted handling for each scenario. The 'browser-incompatible' error indicates the user's browser lacks required WebRTC features--display a message directing users to update or switch browsers. The 'peer-unavailable' error occurs when attempting to connect to a non-existent peer ID--verify the ID and try again.

Network-related errors include 'network' for connection failures to the signaling server and 'server-error' for problems on the server side. These often indicate temporary connectivity issues--implement retry logic and provide clear status updates so users understand what's happening.

The Symmetric NAT Challenge

A small percentage of users connect through symmetric NAT configurations that prevent direct peer-to-peer connections. When two such users attempt to connect, the NAT traversal fails silently. The solution involves TURN (Traversal Using Relays around NAT) servers that relay traffic between peers when direct connection is impossible.

Configure TURN servers in the PeerJS config options to support these users. Public TURN servers are available for development, though production applications should run their own TURN infrastructure for reliability and control. The additional latency introduced by relay servers affects call quality, so TURN should be a fallback rather than the primary connection method.

// Comprehensive error handling
function handlePeerError(err) {
 switch (err.type) {
 case 'browser-incompatible':
 showError('Your browser does not support WebRTC. Please use a modern browser like Chrome, Firefox, or Safari.');
 break;
 case 'peer-unavailable':
 showError('The peer you are trying to connect to is not available. Please check the ID and try again.');
 break;
 case 'network':
 showError('Connection lost. Please check your network connection and try again.');
 reconnectPeer();
 break;
 case 'server-error':
 showError('Server error. Please try again later.');
 break;
 default:
 showError('An error occurred: ' + err.type);
 }
}

Building the User Interface

A phone application requires an intuitive interface that guides users through calling workflows. This section provides guidance on designing the UI elements and connecting them to the underlying PeerJS functionality.

Core UI Components

Design a clean interface with clear visual states for different call stages. The idle state should display available controls for initiating calls--typically a number pad or direct peer ID input. The calling state shows feedback that a call is in progress, possibly with a visual indicator of the remote peer. The connected state displays active call controls including mute, hold, and hangup options.

Include status indicators that communicate application state clearly. Show the current peer ID so users can share it with contacts. Display connection status with clear labels like "Ready," "Connecting," "Connected," and error messages when problems occur. Consider adding audio level indicators during calls to confirm audio transmission.

Connecting UI to Logic

Wire UI elements to the calling functions with appropriate event handlers. The call button should validate inputs (a valid peer ID must be present) and check application state (not already on a call) before initiating. The hangup button triggers the endCall function, with confirmation if the call is active.

// UI event handlers
document.getElementById('callButton').addEventListener('click', () => {
 const peerId = document.getElementById('peerIdInput').value.trim();
 if (!peerId) {
 showError('Please enter a peer ID');
 return;
 }
 callPeer(peerId);
});

document.getElementById('hangupButton').addEventListener('click', () => {
 if (currentCall) {
 endCall();
 }
});

// Update UI based on call state
function updateCallStatus(status) {
 const statusElement = document.getElementById('callStatus');
 statusElement.textContent = status;

 // Update button states
 const callButton = document.getElementById('callButton');
 const hangupButton = document.getElementById('hangupButton');

 callButton.disabled = status === 'Connected' || status === 'Calling...';
 hangupButton.disabled = status !== 'Connected';
}

Production Considerations

Moving from development to production requires additional considerations for reliability, scalability, and user trust. This section addresses key factors for deploying a production-ready phone application.

Security and Privacy

Implement HTTPS for all production deployments--browsers require secure contexts for many WebRTC features, and users expect privacy for voice communications. Obtain an SSL certificate through services like Let's Encrypt for free, automated certificate management.

Consider authentication and authorization for your phone application. Determine whether any users should be prevented from calling others, and implement appropriate access controls. Store call logs securely if your application requires them, and provide users with clear privacy policies explaining how their data is handled.

Scalability

The PeerJS signaling server requires consideration for scalability. The cloud service works for small applications but may become a bottleneck or cost concern at scale. Self-hosting PeerServer allows horizontal scaling through load balancing, though the signaling workload remains relatively light compared to media relaying.

For applications expecting significant concurrent calls, invest in TURN server infrastructure. TURN servers require substantial bandwidth since they relay all media traffic, and capacity planning should account for peak call volumes. Consider cloud-based TURN services for elastic scaling without infrastructure management.

Testing and Quality Assurance

Test your application across browsers and devices to ensure broad compatibility. WebRTC implementations vary between browsers, and certain features may work differently or not at all in some environments. Automated testing with tools like Selenium or Playwright can catch regressions, but manual testing on real devices remains valuable for audio quality assessment.

Conduct network testing that simulates various conditions including high latency, packet loss, and bandwidth limitations. These tests reveal how your application handles adverse conditions and inform decisions about buffering, codec selection, and quality adaptation strategies.

If you're building communication features as part of a larger web application project, our team can help you navigate these production considerations and ensure your implementation meets enterprise standards for reliability and security. We specialize in building real-time communication platforms that scale with your user base while maintaining high-quality audio and video performance.

Advanced Features

Once the core calling functionality is working, consider adding features that enhance the user experience and differentiate your application from basic implementations.

Call Management Features

Implement call waiting to handle incoming calls when already on another call. Call holding allows temporarily suspending a conversation while taking another, with the ability to resume the held call. Conference calling extends the basic peer-to-peer model to support multiple participants, though this requires more complex signaling logic.

Call recording provides value for business users who need to archive conversations. WebRTC supports capturing local and remote streams, which can be combined and saved to files. Consider legal requirements around call recording in your jurisdiction, and implement appropriate consent mechanisms.

Media Enhancements

Explore audio processing options to improve call quality. WebRTC includes built-in acoustic echo cancellation, noise suppression, and auto gain control that work well in many scenarios. For specialized use cases like music transmission, you may need to bypass these processing stages or implement custom solutions.

Video capabilities extend the voice-only phone to video calling. The getUserMedia API supports both audio and video constraints, and PeerJS handles video streams the same way as audio. Adding video requires additional UI elements for displaying remote video and camera preview, as well as bandwidth considerations for maintaining quality.

For teams looking to integrate real-time communication features into their products, our custom software development services can help you build sophisticated communication platforms that leverage these advanced capabilities alongside other features your users need. We have extensive experience implementing WebRTC-based solutions for enterprise communication tools, telehealth platforms, and collaborative applications.

Summary

Building a phone application with PeerJS combines the power of WebRTC with a simplified development experience. The library handles the complex signaling and ICE negotiation that makes WebRTC challenging, allowing developers to focus on user experience and application logic. Through careful attention to error handling, resource cleanup, and production considerations, you can create a reliable communication tool that serves users across diverse environments and conditions.

The journey from basic implementation to production-ready application involves understanding peer connections, media stream handling, and the various states that characterize a call lifecycle. With the foundation established in this tutorial, you have everything needed to build sophisticated communication features that leverage peer-to-peer technology's low latency and privacy advantages.

PeerJS abstracts the complexity of WebRTC while maintaining access to its full capabilities. Whether you're building a simple two-person calling app or a full-featured communication platform, the principles covered here--proper initialization, graceful call handling, comprehensive error management, and production readiness--provide a solid foundation for any real-time communication project. The peer-to-peer architecture offers significant advantages in terms of latency and privacy, making it an excellent choice for applications where these factors matter to your users.

Sources

1. MDN Web Docs: Building an Internet-Connected Phone with PeerJS

2. PeerJS Documentation

3. PeerJS GitHub Repository