PeerJS Server Component

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Your Node.js project is likely running in CommonJS mode, but `peer` v1.0.0+ uses ES Module syntax.
  fix Add `"type": "module"` to your `package.json` file, or rename your server file to have a `.mjs` extension. Ensure all `require()` statements are converted to `import` statements.

• Error: listen EADDRINUSE: address already in use :::9000

  cause Another process is already using the port that your PeerJS server is trying to bind to (e.g., port 9000).
  fix Change the `PEER_PORT` environment variable or the hardcoded port in your server configuration to an available port. Alternatively, identify and terminate the process currently using that port (e.g., `lsof -i :9000` on Linux/macOS or `netstat -ano | findstr :9000` on Windows).

• WebSocket connection to 'ws://localhost:9000/peerjs?id=...' failed: Error during WebSocket handshake: Unexpected response code: 400

  cause The client-side PeerJS configuration (host, port, path) does not match the server-side configuration, or a firewall is blocking the connection.
  fix Verify that the `host`, `port`, and `path` parameters in your client-side `new Peer({...})` constructor exactly match the `PeerServer` configuration on your Node.js server. Ensure no firewalls are blocking connections to the specified port.

Warnings

• breaking Version 1.0.0 of `peer` (peerjs-server) introduced a shift towards ESM-only environments, which may break applications still relying on CommonJS `require()` syntax. Additionally, the underlying WebSocket library `ws` was updated to v8.
  Fix: Migrate your project to use ES module import syntax (`import ... from 'peer'`) and ensure your Node.js environment is configured for ESM (e.g., using `"type": "module"` in `package.json` or `.mjs` file extensions). Review `ws` v8 breaking changes if upgrading from older versions.
• gotcha Running the PeerJS server on well-known ports (e.g., 80 or 443) often requires elevated privileges or careful reverse proxy configuration. Node.js applications typically run as unprivileged users.
  Fix: Consider running the PeerJS server on a non-privileged port (e.g., 9000 as in the quickstart) and use a reverse proxy like Nginx or Caddy to forward requests from standard HTTP/HTTPS ports. Ensure your proxy correctly handles WebSocket connections.
• gotcha The `allow_discovery: true` option (demonstrated in quickstart) enables clients to list all active Peer IDs on the server. While convenient for development, it can be a privacy and security concern in production environments.
  Fix: For production deployments, consider setting `allow_discovery: false` to disable ID listing. Implement your own secure mechanism for clients to exchange Peer IDs, such as a separate authentication service or direct sharing.

Install

• npm install peer npm
• yarn add peer yarn
• pnpm add peer pnpm

Imports

• PeerServer
  wrong:

  const PeerServer = require('peer').PeerServer;

  correct:

  import { PeerServer } from 'peer';

  Since v1.0.0, the package primarily targets ESM environments. While CommonJS might still work, ESM is the recommended and best-supported import method for Node.js versions >=14.
• ServerOptions

  import { ServerOptions } from 'peer';

  Import the `ServerOptions` interface for type-checking and autocompletion when configuring the PeerServer.
• Application
  wrong:

  const express = require('express');

  correct:

  import express, { Application } from 'express';

  PeerJS server can be integrated into an existing Express application. Ensure Express is imported correctly.

Quickstart

This quickstart demonstrates how to set up and run the PeerJS server using TypeScript, integrating it with an Express application to serve static content. It includes configuration for port and path via environment variables, basic error handling for port conflicts, and graceful shutdown.

import { PeerServer } from 'peer';
import express from 'express';
import { createServer } from 'http';
import path from 'path';

// Define the port and path for the PeerJS server, allowing environment variable overrides.
const PEER_PORT = process.env.PEER_PORT ? parseInt(process.env.PEER_PORT, 10) : 9000;
const PEER_PATH = process.env.PEER_PATH || '/myapp'; // Use a distinct path for isolation

// Create an Express application to serve static files or handle other API routes.
const app = express();

// Serve a basic static HTML file from a 'public' directory.
// Make sure to create a 'public' directory with an 'index.html' for this example to run fully.
app.use(express.static(path.join(__dirname, '../public')));

// Create an HTTP server that will host both the Express app and the PeerJS WebSocket server.
const httpServer = createServer(app);

// Initialize PeerJS server and attach it to the existing HTTP server.
// The `PeerServer` function creates an instance that listens for WebSocket connections.
const peerServer = PeerServer({
  port: PEER_PORT,
  path: PEER_PATH,
  allow_discovery: true, // Enables client discovery (optional, security consideration)
  // For production, consider adding key and cert for HTTPS
  // key: fs.readFileSync('path/to/key.pem'),
  // cert: fs.readFileSync('path/to/cert.pem'),
}, (server) => {
  console.log(`PeerJS server initialized.`);
  console.log(`  - WebSocket endpoint: ws://localhost:${PEER_PORT}${PEER_PATH}`);
  console.log(`  - Server ID: ${server.id}`);
});

// Listen on the specified port for HTTP and WebSocket connections.
httpServer.listen(PEER_PORT, () => {
  console.log(`HTTP server (for static content) listening on port ${PEER_PORT}`);
  console.log('Access the client at http://localhost:9000/index.html');
});

// Handle server errors
httpServer.on('error', (err: NodeJS.ErrnoException) => {
  if (err.code === 'EADDRINUSE') {
    console.error(`Port ${PEER_PORT} is already in use. Please choose another port or terminate the existing process.`);
  } else {
    console.error(`Server error: ${err.message}`);
  }
  process.exit(1);
});

// Graceful shutdown
process.on('SIGINT', () => {
  console.log('Shutting down server...');
  peerServer.destroy(() => {
    httpServer.close(() => {
      console.log('Server gracefully shut down.');
      process.exit(0);
    });
  });
});