Verani

Verani is a dedicated realtime SDK designed for Cloudflare's Durable Objects (Actors), offering a familiar developer experience inspired by Socket.io. It focuses on simplicity and efficiency, delivering seamless interaction patterns for realtime applications.

Key Features

• Familiar API: Developers familiar with Socket.io will find Verani easy to use and integrate into their projects.
• Hibernation Support: The SDK efficiently manages Cloudflare Actor hibernation, ensuring consistent performance without manual intervention.
• Type Safety: Built using TypeScript, Verani provides full type safety, enhancing developer experience and minimizing runtime errors.
• Intuitive Architecture: With clear concepts of rooms, channels, and broadcasting, Verani simplifies the process of building realtime communication features.
• Modern Developer Experience: Features like automatic reconnection, error handling, and connection lifecycle management are included, streamlining the developer workflow.

Installation

Simply add Verani to your project using npm or bun:

npm install verani @cloudflare/actors
# or
bun add verani @cloudflare/actors

Quick Start Example

Server Side (Cloudflare Worker)

Define rooms for your application and register event handlers:

import { defineRoom, createActorHandler } from "verani";

export const chatRoom = defineRoom({
  name: "chatRoom",
  websocketPath: "/chat",

  onConnect(ctx) {
    console.log(`User ${ctx.meta.userId} connected`);
    ctx.actor.emit.to("default").emit("user.joined", { userId: ctx.meta.userId });
  },

  onDisconnect(ctx) {
    console.log(`User ${ctx.meta.userId} disconnected`);
    ctx.actor.emit.to("default").emit("user.left", { userId: ctx.meta.userId });
  }
});

chatRoom.on("chat.message", (ctx, data) => {
  ctx.actor.emit.to("default").emit("chat.message", {
    from: ctx.meta.userId,
    text: data.text,
    timestamp: Date.now()
  });
});

export const ChatRoom = createActorHandler(chatRoom);

Client Side

Connect to your Cloudflare Worker and listen for messages:

import { VeraniClient } from "verani";

const client = new VeraniClient("wss://your-worker.dev/ws?userId=alice", {
  pingInterval: 5000,
  pongTimeout: 5000,
  reconnection: {
    enabled: true,
    maxAttempts: 10,
    initialDelay: 1000,
    maxDelay: 30000
  }
});

client.on("chat.message", (data) => {
  console.log(`${data.from}: ${data.text}`);
});

client.emit("chat.message", { text: "Hello, world!" });

Comprehensive Documentation

For more details on installation, API references, best practices, and advanced configuration options, refer to the following sections:

• Getting Started
• API Reference
• Guides
• Examples

Examples and Live Demos

Explore practical implementations of Verani through hosted examples demonstrating chat, notifications, and presence functionality. Clone the repository and run the provided examples:

git clone https://github.com/v0id-user/verani
cd verani
bun run dev  # or npm run dev

Project Status

Verani is currently under active development, supporting core realtime messaging features, hibernation management, and client reconnection capabilities. The roadmap includes advanced features such as framework adapters for broader integration.

**Explore the simplicity and power of building realtime applications with Verani.