Skip to content
Documentation
Getting Started

Getting Started

Peerix is a focused JavaScript library that makes building WebRTC peer-to-peer apps simple and reliable. Peerix uses WebRTC for peer-to-peer communication and relies on a signaling mechanism to facilitate peer discovery and connection management. The library abstracts away the complexities of WebRTC and provides a simple API for developers to create real-time peer-to-peer applications with media streaming and data sharing capabilities.

The following diagram provides a high-level overview of the Peerix architecture and its components:

    graph TD
  PX{{Peerix}} --> SD(Signaling Drivers)
  SD --> SS[Signaling Servers]
  PX --> ICE[STUN/TURN Servers]
  PX --> PC(Peers)
  PC --> LCE(Lifecycle Events)
  PC --> MS(Media Streams)
  PC --> DC(Data Channels)
  PX --> ADD(Add-ons)

Peerix consists of several key components:

  • Peers: The core component that manages the peer-to-peer connection, including media streams and data channels.
    • Lifecycle Events: Handles events related to peer connections, such as joining/leaving rooms and connection state changes.
    • Media Streams: Handles audio and video streams between peers.
    • Data Channels: Manages arbitrary data communication between peers.
  • Signaling Drivers: Abstracts the signaling process, allowing you to choose or implement your own signaling method.
    • Signaling Servers: Responsible for peer discovery and message exchange between peers.
    • STUN/TURN Servers: Used for NAT traversal and media relay when direct peer-to-peer communication is not possible.
  • Add-ons: Extend the functionality of Peerix with additional features or integrations.

Installation

Install the Peerix library using your preferred package manager:

npm install peerix

Using CDN

If you prefer to use a CDN without installing it as a package, you can include the library directly in your HTML file using a script tag. This allows you to quickly get started with Peerix without needing to set up a build process or package manager.

ES Modules

If you want to use the ESM version of Peerix, you can import the library as follows:

<script type="module">
  import { Peer, BroadcastChannelDriver } from 'https://esm.sh/peerix';
</script>

Alternatively, you can use an import map to simplify the imports in your JavaScript code:

<script type="importmap">
  {
    "imports": {
      "peerix": "https://esm.sh/peerix@latest"
    }
  }
</script>
<script type="module">
  import { Peer, BroadcastChannelDriver } from 'peerix';
</script>

UMD modules

If you prefer to use the UMD version of Peerix for broader compatibility, you can include it as follows:

<script src="https://unpkg.com/peerix"></script>
<script>
  const { Peer, BroadcastChannelDriver } = window.peerix;
</script>

Basic Usage

Use the Peerix library in your JavaScript or TypeScript project to create peer-to-peer applications. Below is a simple example that demonstrates how to set up a Peer instance with a specific signaling driver, open a data channel, and exchange messages between peers:

import { Peer, BroadcastChannelDriver } from 'peerix';

// create a signaling driver
const driver = new BroadcastChannelDriver();

// create the Peer instance
const peer = new Peer({ driver });

// listen for open channel event
peer.on('channel:open', (e) => {
  const { remote, label } = e;
  const { name } = remote.metadata;
  remote.send(`Hello, ${name}!`, { label });
});

// listen for incoming messages
peer.on('channel:message', (e) => {
  const { remote, data } = e;
  const { name } = remote.metadata;
  console.log(`Received message from ${name}:`, data);
});

// open a data channel
peer.open({ label: 'chat' });

// join a room
peer.join({ room: 'room-id', metadata: { name: 'Guest' } });

You can run the above code in multiple browser tabs to see the peer-to-peer communication in action. Each tab will represent a peer that can connect to the same room and exchange messages via WebRTC data channel.

Sandbox

Try out the Peerix library in the sandbox environment below. You can open multiple tabs with the sandbox in the same browser to simulate multiple peers and see how they interact with each other using Peerix.

DocumentationPeers