Welcome to Erebus (Beta)

Erebus is an early-stage real-time infrastructure platform. At this stage you get one core primitive with two behaviors built in:

• Pub/Sub Channels — publish and subscribe to ordered messages using ULID sequences so delivery order is guaranteed.
• Presence — presence events are part of channels. When clients connect and subscribe to a room, presence state is updated automatically and fired out to everyone in that channel.
• Acknowledgments — an MQTT-style ack system with QoS 1 support. Every message is delivered at least once and acknowledged by subscribers.

That is the foundation. One channel gives you both messaging and awareness of who is in the room.

When you connect, you are placed in the nearest point of presence (PoP). Everyone in that region shares the same local channel object, so ordering and presence are consistent without global lag.

How Erebus infrastructure works

Erebus is built on top of Cloudflare Durable Objects.

In short, Durable Objects are distributed V8 isolates that can run across Cloudflare’s global network. Once a Durable Object is created and mapped to a namespace, it keeps the same location, which makes it easy to persist state.

Because they are V8 instances, they can also hibernate and scale down to zero when idle. That means Erebus runs serverless by design, so you only pay for what you actually use.

A deep dive into the choices behind Erebus infrastructure check our blog Why Cloudflare Durable Objects?.

🚀 Quick Start

Get up and running in minutes:

1. Install the SDK

npm install @erebus-sh/sdk

2. Choose Your Path

3. Basic Example

import { ErebusClient, ErebusClientState } from "@erebus-sh/sdk/client";

const client = ErebusClient.createClient({
  client: ErebusClientState.PubSub,
  authBaseUrl: "https://your-auth-server.com"
});

// Join a channel and connect
client.joinChannel("my-app");
await client.connect();

// Subscribe to messages
await client.subscribe("notifications", (msg) => {
  console.log("📩 New notification:", msg.payload);
});

// Publish a message
await client.publish("notifications", "Hello from Erebus! 👋");

🎯 Real-World Use Cases

Chat & Messaging

• Real-time messages with guaranteed ordering
• Presence tracking to show who's online
• Message history for catching up on missed conversations

// Chat room with presence
await client.subscribe("chat:general", displayMessage);
await client.onPresence("chat:general", updateUserList);
await client.publish("chat:general", "Hello everyone!");

Live Collaboration

• Operational transforms for collaborative editing
• Cursor tracking for multi-user editing
• Conflict resolution with ULID sequences

// Document collaboration
await client.subscribe("doc:123", applyEdit);
await client.publish("doc:123", JSON.stringify({
  type: "insert", position: 10, text: "Hello"
}));

Real-time Notifications

• Targeted delivery to specific users
• Delivery confirmations with acknowledgments
• Push notification integration

// Send notification with confirmation
await client.publishWithAck(
  `user:${userId}`,
  JSON.stringify({ title: "New Message", urgent: true }),
  (ack) => console.log("Delivered:", ack.success)
);

Live Analytics

• Real-time metrics streaming
• Event aggregation across multiple clients
• Dashboard updates without polling

// Stream analytics events
client.publish("analytics:pageview", JSON.stringify({
  page: "/dashboard", userId, timestamp: Date.now()
}));

🏗️ Architecture Benefits

Edge-First Design

• Global distribution with Cloudflare's 300+ locations
• Automatic scaling with Durable Objects
• Zero-cost idle - pay only for active usage

Developer Experience

• TypeScript-first with full type safety
• Framework agnostic - works with any JavaScript runtime
• Production ready with error handling and reconnection

Reliability Features

• Message ordering guaranteed with ULID sequences
• Automatic reconnection with exponential backoff
• QoS 1 support - at-least-once delivery with acknowledgments

📚 What's in the Documentation

Advanced Topics

• Schema Validation - Type-safe messaging with Zod
• Connection Management - Robust connection handling
• Error Patterns - Production-ready error handling

🎯 Choose Your Starting Point

I want to build something quickly

→ Core SDK Quickstart

• Working example in 3 minutes
• Copy-paste authentication server
• Immediate publish/subscribe functionality

I'm building a React app

→ React SDK Quickstart

• React hooks integration
• Declarative subscriptions
• Built-in state management

I need bulletproof type safety

→ Schema Facade Guide

• Runtime validation with Zod
• Prevent payload mismatches
• IDE autocompletion for message types

I'm integrating into existing infrastructure

→ Installation Guide

• Framework-specific setup
• Environment configuration
• Production deployment patterns

Status: Beta. Channels with ordered messages and built-in presence are live. More primitives will grow from here.