Demystifying WebRTC: A Step By Step Guide to Peer-to-Peer Video in React

Khadijah — Tue, 15 Sep 2026 07:57:34 +0000

Introduction
When I decided to build a telemedicine app for my capstone project, I knew it had to have video call as one of its features, the question was how I was to implement it.
I had first thought of using third-party apps like Agora and Twillio, but I was a uni student with a tight budget and big dreams. I thought to myself if my app suddenly takes off, then I'd need money to rely on third-party apps. Also, I had a really big ego and convinced myself it couldn’t be that hard.
There began my journey of looking up WebRTC tutorials, and I was even more confused than I first began. I spent days trying to figure out how browsers actually “handshake” using servers and how to keep the connection from dropping.
That is why I decided to write this guide. To help beginners understand WebRTC and provide a straight-to-the-point tutorial on how to hook up React frontend to a Node.js signalling server so two users can actually see and hear each other.
Prerequisites and tech stack
Before I drop the full component code, there are a couple of things you need to know about how React handles webRTC.
If you try to manage your peer connection or video streams using standard React (useState), you are going to have a really hard time. WebRTC changes state constantly if your component rerenders every time and the ICE candidate drops or a stream updates. Your video feed will either stutter, freeze or completely crash.
This is why we lean heavily on two specific hooks:
const localVideoRef = useRef(null);
const remoteVideoRef = useRef(null);
const peerRef = useRef(null);
const callRef = useRef(null);
// Assigning the PeerJS instance directly to ref
peerRef.current = peer;
// Assigning active call object to ref without causing UI re-renders
callRef.current = call;
useRef: this is the secret sauce that lets us hold onto the RTCpeer connection instance and the socket connection across renders without triggering a UI refresh. It keeps our connection stable while React does it’s thing.
// Runs once peer library is ready to handle setup
useEffect(() => {
if (!peerLoaded) return;
let cleanup;
const init = async () => {
try {
setError('');
// Request camera and microphone access
const stream = await navigator.mediaDevices.getUserMedia({
video: { width: { ideal: 1280 }, height: { ideal: 720 } },
audio: true,
});
setLocalStream(stream);
if (localVideoRef.current) localVideoRef.current.srcObject = stream;

  // ... Initialize PeerJS instance and event listeners
} catch (err) {
  setError(`Camera/microphone access error: ${err.message}`);
}

};
init();
return () => cleanup?.();
}, [peerLoaded]);
useEffect: we use this to run our initialisation logic when the user page loads. This is also where the user is asked for camera permission as well as microphone permission.
The mental model (how it works under the hood)
Before we look at the code and inspect it, we need to talk about how webRTC actually connects two people.
If you are someone that does web development, you know the client-server model: your browser talks to a server, and the server talks back. WebRTC throws that out the window. It wants Browser A to talk directly to Browser B without a middleman.
This may sound simple but think of how the internet works. Browsers sit behind NAT and firewalls, so they don't know each other's real public IP addresses, also firewalls block unsolicited incoming connections by default.
To break through this and start a video call, your app has to handle three core phases. Think of it like organising a blind date:
Media stream (the outfits)
Before going on a date, you need to think of an outfit. In webRTC terms this means capturing your local data. We use the browser's getUserMedia API to turn on the camera and microphone. This creates a MediaStream. We need this stream ready to go so we can hand it over to the connection once it's established.
The signalling server (the matchmaker)
Since our browsers cannot find each other on their own, they need something called the Signaling server. This acts like a temporary matchmaker.
Basically what happens is that Browser A says, "Hey, here are the video formats I support and my connection settings (Offer)."
The signalling server passes that to Browser B, which replies, "Cool, here are my settings (Answer)."
The peer connection (the handshake)
We're using PeerJS, a library that wraps the raw WebRTC APIs, it handles the offer/answer/ICE exchange for you so you don't have to write that signaling logic by hand.
Now we are thinking, how do the browsers actually find a physical path to each other through all the internet routers and firewalls? They use what we call ICE Candidates and STUN servers.
A STUN server is just a public server that looks at your browser and says, "Hey, here is what your public IP address actually looks like to the outside world."
The browsers collect these public routing pathways (ICE candidates), swap them through the matchmaker, find the shortest path to each other, and lock in the direct peer connection.
Now, data flows straight between the users, bypassing any servers completely.
The step-by-step implementation
Now for the part we have been waiting for, the actual execution. We are going to look at how this component handles media streams, automates the connection handshake, and handles incoming calls.
Step 1: grabbing the user’s microphone and camera
Before we can connect to anyone, we need our own audio and video feeds. We do this inside a useEffect hook using the browser's native navigator.mediaDevices.getUserMedia API.
const stream = await navigator.mediaDevices.getUserMedia({
video: { width: { ideal: 1280 }, height: { ideal: 720 } },
audio: true,
});
setLocalStream(stream);
if (localVideoRef.current) localVideoRef.current.srcObject = stream;
What is happening here:
We ask the browser for permission to use the webcam (targeting a 720p resolution) and the microphone. Once the user allows it, the browser gives us a MediaStream object. We save this stream to our React state so we can attach it to our local element via a useRef hook.
Step 2: The "Smart Room" Strategy (Automating the Handshake)
Usually, WebRTC tutorials make you copy and paste long, random string IDs across screens just to connect two users. For a real app, it is awful for user experience.
Instead, we can use the appointmentId directly from the URL path (/video-call/:appointmentId) along with the user's role from localStorage to generate matching IDs automatically.
const role = user?.role === 'doctor' ? 'doctor' : 'patient';
const myPeerId = appointmentId ? ${role}-${appointmentId} : null;
const theirPeerId = appointmentId ? ${role === 'doctor' ? 'patient' : 'doctor'}-${appointmentId} : null;
Why does it matter?
If the appointment ID in the URL is abc123, the doctor's browser registers itself with PeerJS as doctor-abc123 and expects to talk to patient-abc123. The patient does the exact opposite. They both know who to look for without exchanging a single message manually.
Step 3: Initialising the Peer and Setting up the Listeners
Once PeerJS loads from the CDN, we initialise our peer instance using our smart room IDs and standard Google STUN servers (which help the browsers find each other's public IP addresses).
const peer = myPeerId
? new window.Peer(myPeerId, peerConfig)
: new window.Peer(peerConfig);
peerRef.current = peer;
Immediately after creating the peer instance, we set up an event listener to handle incoming calls (peer.on('call')):
peer.on('call', (call) => {
setConnectionStatus('connecting');
callRef.current = call;
call.answer(stream); // Answer the call with our local camera stream

call.on('stream', (remoteStream) => {
// Attach the other person's video to our remote video element
if (remoteVideoRef.current) remoteVideoRef.current.srcObject = remoteStream;
setConnectionStatus('connected');
});
});
When Doctor A is sitting in the room and Patient B tries to call, the doctor's browser detects the incoming call event, automatically answers it by passing their own local camera stream, and hooks the patient's incoming stream directly into the remote video player.
Step 4: The Auto-Call Trigger
To make the connection truly seamless, we don't want the user to click a "Call" button. We want the patient to automatically dial the doctor as soon as they join the room.
setPeerId(id);
if (theirPeerId && role === 'patient') {
setTimeout(() => autoCall(stream, theirPeerId), 2000);
}
});
Why the delay?
We add a small 2-second setTimeout buffer here. If the patient enters the room slightly faster than the doctor, the doctor's peer instance might not be registered yet, resulting in a failed connection. This brief delay gives the doctor's side enough time to initialise.
Conclusion
Here's the part I didn't mention earlier, the first version of my video call feature was very generic. I'd basically stitched together the bare minimum and called it a day, still riding on the confidence I mentioned in the intro.
Then I presented it at my capstone jury. I put the call on, and the lecturers just looked at me and said it wasn't working. I was confused; I could see the video on my end, so what were they talking about? Turns out there's a way to tell when a video signal actually isn't flowing, even if the UI looks fine, and I had no idea how they could spot that from across the room.
One of them suggested I look into how Google Classroom handled its video calls, since it is open source. I wasn't about to lift their whole architecture, a telemedicine app has security requirements a classroom app doesn't need to think about, but I used it as a reference point. I went back, rebuilt the connection logic with that as inspiration, and worked with an LLM to help me bring it to life.
Writing this article made me realise that I still have more work to do in regard to my video call feature on my app. I've tested this setup on home wifi and mobile data, across different devices, in different places, and it works. But going through it step by step to explain it to you made me realise I've never once tested it on a locked-down network. Right now, the code only uses STUN servers, which is enough to find a direct path between two people on most networks. But stricter firewalls block that entirely, and the only real fix is a TURN server as a fallback, something I don't have set up yet but is now on my list.
I'm sharing that because I'm not writing this as someone who's already got it all figured out. I'm a beginner who happened to solve this before you did, and I'm still finding gaps in my own understanding as I go. If you're building this for something people will actually rely on, especially anyone connecting from a hospital, office, or anywhere with a strict firewall, take some time to add a TURN server before you call it done. Don't make my mistake of assuming "it worked when I tested it" means "it'll work everywhere."

DEV Community: Khadijah

Demystifying WebRTC: A Step By Step Guide to Peer-to-Peer Video in React