Get started

Install Erebus SDK

Quick installation guide for the Erebus SDK

Install Erebus SDK

Quick guide to installing the Erebus SDK in your JavaScript/TypeScript project.

Installation

npm install @erebus-sh/sdk

Package Structure

The Erebus SDK is organized into focused packages:

Core Packages

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

// React hooks (experimental)
import { ErebusProvider, useChannel } from "@erebus-sh/sdk/react";

// Server-side adapters
import { createGenericAdapter } from "@erebus-sh/sdk/server";

// Service utilities  
import { ErebusService, Access } from "@erebus-sh/sdk/service";

// TypeScript schemas
import type { MessageBody, PresencePacket } from "@erebus-sh/sdk";

Package Exports

Import PathDescriptionStability
@erebus-sh/sdk/clientCore client APIs✅ Semi-Stable
@erebus-sh/sdk/serverServer adapters✅ Semi-Stable
@erebus-sh/sdk/serviceService utilities✅ Semi-Stable
@erebus-sh/sdk/reactReact hooks⚠️ Experimental
@erebus-sh/sdkBarrel exports (legacy)🔄 Will change

Stability

All Erebus SDK packages are currently classified as semi-stable while we continue to refine the platform during the beta phase. Stability levels will be updated as we approach general availability, ensuring you always have clear guidance on production readiness.


Verify Installation

Quick test to ensure the SDK is installed correctly:

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

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

console.log("✅ Erebus SDK installed successfully");

Environment Setup

Development Environment

Create a .env.local file for development:

.env.local
# Erebus Configuration
SECRET_API_KEY=your_secret_api_key_here
EREBUS_AUTH_URL=http://localhost:4919
EREBUS_WS_URL=ws://localhost:8787

# Development Settings
NODE_ENV=development
DEBUG=true

Production Environment

.env.production
# Erebus Configuration
SECRET_API_KEY=your_production_api_key
EREBUS_AUTH_URL=https://your-auth-server.com
# EREBUS_WS_URL defaults to wss://gateway.erebus.sh

# Production Settings
NODE_ENV=production
DEBUG=false

Environment Variables

VariableRequiredDescriptionDefault
SECRET_API_KEY✅ YesYour Erebus API keyNone
EREBUS_AUTH_URL✅ YesYour auth server URLNone
EREBUS_WS_URL❌ NoWebSocket URLwss://gateway.erebus.sh
NODE_ENV❌ NoEnvironment modedevelopment

Current Limitations

Erebus SDK doesn't automatically pick the environment variables, you need to set them manually.


Next Steps

After successful installation, choose your implementation path:

Start here for vanilla JavaScript/TypeScript, Node.js, or any JavaScript runtime:

The Core SDK guides include framework-specific examples for Express.js, Node.js servers, and more.

⚛️ React SDK (Experimental)

For React applications and Next.js:

The React SDK guides include complete Next.js, Vite, and Create React App setup instructions.

📚 Advanced Topics


Community & Support