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 Path | Description | Stability |
---|---|---|
@erebus-sh/sdk/client | Core client APIs | ✅ Semi-Stable |
@erebus-sh/sdk/server | Server adapters | ✅ Semi-Stable |
@erebus-sh/sdk/service | Service utilities | ✅ Semi-Stable |
@erebus-sh/sdk/react | React hooks | ⚠️ Experimental |
@erebus-sh/sdk | Barrel 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:
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:
# 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
# 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
Variable | Required | Description | Default |
---|---|---|---|
SECRET_API_KEY | ✅ Yes | Your Erebus API key | None |
EREBUS_AUTH_URL | ✅ Yes | Your auth server URL | None |
EREBUS_WS_URL | ❌ No | WebSocket URL | wss://gateway.erebus.sh |
NODE_ENV | ❌ No | Environment mode | development |
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:
🚀 Core SDK (Recommended)
Start here for vanilla JavaScript/TypeScript, Node.js, or any JavaScript runtime:
- Core Quickstart - Basic publish/subscribe example
- Core API Reference - Complete API documentation
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:
- React Quickstart - Next.js integration with hooks
- React Provider Setup - Context provider configuration
The React SDK guides include complete Next.js, Vite, and Create React App setup instructions.
📚 Advanced Topics
- Schema Validation - Type-safe messaging
- Connection Management - Robust connection handling
- Message History - Historical message retrieval
Community & Support
- GitHub Repository - Source code and examples
- GitHub Issues - Bug reports and feature requests
- Examples - Complete working examples
- Direct Support - For complex issues or feedback