Simple Presence

Prerequisites

A JavaScript/TypeScript project (React, SolidJS, or plain JS/TS)
A Simple Presence account — sign up free

1. Create an App

2. Install the SDK

Pick the package for your framework:

npm install @simple-presence/react

For other frameworks, install @simple-presence/solid-js or @simple-presence/core.

3. Add Presence to a Component

Use the usePresenceCount hook with any tag string and your app key:

App.tsx

import { usePresenceCount } from "@simple-presence/react";

function OnlineUsers() {
  const count = usePresenceCount("homepage", {
    appKey: "your-app-key",
  });

  return (
    <div className="flex items-center gap-2">
      <span className="h-2 w-2 rounded-full bg-green-500" />
      <span>{count} online now</span>
    </div>
  );
}

That's it. The count updates in real time as users join and leave the page.

4. Vanilla / Framework-Agnostic

If you're not using React or SolidJS, the core package works anywhere:

presence.ts

import { SimplePresence } from "@simple-presence/core";

const presence = new SimplePresence({
  tag: "homepage",
  appKey: "your-app-key",
  onCountChange: (count) => {
    document.getElementById("count")!.textContent = String(count);
  },
});

// Later, when the user navigates away:
presence.destroy();

5. Advanced: History & Peak

Use usePresence for richer data including historical counts and peak analytics:

Analytics.tsx

import { usePresence } from "@simple-presence/react";

function PresenceAnalytics() {
  const { count, history, peak, peakAt, refresh } = usePresence("dashboard", {
    appKey: "your-app-key",
  });

  return (
    <div>
      <p>Current: {count} users</p>
      <p>
        Peak: {peak} at {peakAt?.toLocaleTimeString()}
      </p>
      <p>History points: {history.length}</p>
      <button onClick={refresh}>Refresh stats</button>
    </div>
  );
}

What happens under the hood

The SDK opens a WebSocket to Cloudflare's edge network, nearest to the user.

A Durable Object aggregates all connections for your app key + tag combination.

When a user joins or leaves, the updated count is broadcast to all subscribers instantly.

Tab visibility is tracked automatically — users are marked "away" when they switch tabs.

Next steps

React SDK — full API for usePresenceCount and usePresence
SolidJS SDK — reactive primitives with createPresenceCount
Core SDK — framework-agnostic SimplePresence class
API Reference — types, schemas, and configuration options

Quick Start