Quickstart Example

Getting started with Erebus takes just a few steps:

An API endpoint that creates tokens for your clients using your API keys

Install

In this example for the API endpoint I will be using Bun.Serve, you can use any other server framework you prefer.

npm install @erebus-sh/sdk

First, create a client instance. Specify the client type and your auth domain (authBaseUrl). If you’re running locally, also set the wsBaseUrl; otherwise it defaults to wss://gateway.erebus.sh.

index.ts

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

const client = ErebusClient.createClient({
  client: ErebusClientState.PubSub,
  authBaseUrl: "http://localhost:4919",  // your auth domain
  wsBaseUrl: "ws://localhost:8787",  // your ws domain (optional if you self-host locally)
});
...

Create the adapter instance. The authorize function is used to authorize the client to join the channel and allow the topics.

Fire Webhook

The fireWebhook function is used to handle the webhook messages, when any webhook publish happens in the service, it will fire it there. Just make sure you specify the base domain in the platform project settings.

index.ts

// ... Previous code ...
// Imports go to top of the file ofc
import { createGenericAdapter } from "@erebus-sh/sdk/server";
import { Access, ErebusService } from "@erebus-sh/sdk/service";
import Bun from "bun";

const SECRET_API_KEY = process.env.SECRET_API_KEY || "demo-secret-key"; // replace with your own secret_api_key from the platform


const app = createGenericAdapter({
  authorize: async (channel, ctx) => {
    // Normally you'd check cookies, headers, or DB here
    const userId = Math.random().toString(36).substring(2, 15);

    const service = new ErebusService({
      secret_api_key: SECRET_API_KEY,
      base_url: "http://localhost:3000", // (optional if you self-host locally) where your Erebus service is running
    });

    // Create a session for this user
    const session = await service.prepareSession({ userId });

    // Join the requested channel
    session.join(channel);

    // Allow reads + writes
    session.allow("*", Access.ReadWrite);

    return session;
  },
  fireWebhook: async (message) => {
    // You can handle the webhook message here
  },
});

Bun.serve({
  port: 4919,
  fetch: app.fetch,
});

console.log("✅ Auth server running at http://localhost:4919");

Now create your main functon and start using the client.

Join a channel first

You need to join a channel first before you can subscribe to it. Refer to the Channels section for more information.

index.ts

// ... Previous code ...

async function main() {
  const topic = "room1";
  // Join a channel first
  client.joinChannel("chats");
  // Connect
  await client.connect();
  
  // Subscribe to a channel
  await client.subscribe(topic, (msg) => {
    console.log("📩 Received:", msg.payload, "from", msg.senderId);
  });

  await client.onPresence(topic, (presence) => {
    console.log("📩 Presence:", presence);
  });

  // Publish a message
  await client.publishWithAck(topic, "Hello Erebus 👋", (ack) => {
    console.log("✅ Message acknowledged:", ack.success ? "Success" : "Failed");
  }, 3000);
}

main().catch(console.error);

Full code example: examples/chat-ts/index.ts

Quickstart Example

Quickstart: Publish & Subscribe with the Core SDK

On this page