@releaseo/react

Headless React adapter for Releaseo, with provider state, hooks, identity sync, and SSR-safe snapshots.

Install

npm install @releaseo/sdk-core @releaseo/react

Provider

The adapter is headless. It initializes @releaseo/sdk-core, exposes React state/actions, and keeps the UI inside the Releaseo iframe.

import { ReleaseoProvider } from "@releaseo/react";

export function App() {
  return (
    <ReleaseoProvider config={{ publishKey: "pk_live_xxx" }}>
      <AppShell />
    </ReleaseoProvider>
  );
}

For tenant, organization, or project switches, pass a stable resetKey.

<ReleaseoProvider config={releaseoConfig} resetKey={`${tenant.id}:${project.id}`}>
  <AppShell />
</ReleaseoProvider>

Use resetOnUnmount only when the provider is intentionally tied to a route or microfrontend lifecycle and should tear down the SDK after unmount.

Open button and unread count

import { useReleaseo, useReleaseoUnread } from "@releaseo/react";

export function WhatsNewButton() {
  const { isReady, open } = useReleaseo();
  const unread = useReleaseoUnread();

  return (
    <button type="button" disabled={!isReady} onClick={() => void open()}>
      What's new {unread > 0 ? `(${unread})` : null}
    </button>
  );
}

Identity sync

Use useReleaseoIdentity() after auth and tenant context are known.

import { useReleaseoIdentity } from "@releaseo/react";

export function ReleaseoIdentitySync({ user, tenant }: Props) {
  useReleaseoIdentity({
    userId: user?.id,
    enabled: Boolean(user && tenant),
    identityKey: user && tenant ? `${user.id}:${tenant.id}` : null,
    properties:
      user && tenant
        ? { email: user.email, name: user.name, tenantId: tenant.id, plan: tenant.plan }
        : undefined,
    logoutOnDisable: true,
  });

  return null;
}

identityKey controls when the hook calls identify(). Include tenant or organization ids when those should create a new SDK session.

Hooks

Hook	Purpose
`useReleaseo()`	Full snapshot plus runtime actions.
`useReleaseoStatus()`	Derived status such as `idle`, `ready`, `identified`, or `error`.
`useReleaseoUnread()`	Current unread count from the widget.
`useReleaseoSettings()`	Resolved SDK/widget settings snapshot.
`useReleaseoError()`	Runtime error state.
`useReleaseoIdentity(options)`	Safe identity synchronization.
`useReleaseoEvent(eventName, handler)`	Subscribe to SDK lifecycle events.
`useReleaseoSelector(selector)`	Subscribe to a narrow slice of SDK state.

Next.js App Router

Render the provider from a client component.

"use client";

import { ReleaseoProvider } from "@releaseo/react";

export function ReleaseoClientProvider({ children }: { children: React.ReactNode }) {
  return <ReleaseoProvider config={{ publishKey: "pk_live_xxx" }}>{children}</ReleaseoProvider>;
}

The adapter is SSR-safe. Server rendering receives an idle snapshot and runtime work starts from client-side effects.