@perkamo/react

React provider and hooks for the Perkamo browser SDK. Works in any React 18.2+ or 19 app — Vite, Remix, React Router, CRA, or custom setups. Next.js apps should prefer @perkamo/nextjs, which adds server route helpers on top.

Install

npm install @perkamo/react

Security model

Never put server API keys in frontend code. Your backend mints short-lived client tokens; the React client asks for them on demand — either through a tokenEndpoint your backend exposes, or a custom getToken function.

Quickstart

import { PerkamoProvider, usePerkamoCustomerJson } from "@perkamo/react";

function App() {
  return (
    <PerkamoProvider tokenEndpoint="/auth/perkamo/token">
      <LoyaltyBadge />
    </PerkamoProvider>
  );
}

function LoyaltyBadge() {
  const { customer, loading, error } = usePerkamoCustomerJson();
  if (loading) return <span>Loading…</span>;
  if (error || !customer) return null;
  return <span>Level {customer.level.level}</span>;
}

The tokenEndpoint is POSTed with credentials included and must return { "token": "..." } minted by your backend with a Perkamo server SDK.

Custom token provider

<PerkamoProvider getToken={async () => fetchMyPerkamoToken()}>
  {children}
</PerkamoProvider>

Prebuilt client

import { createPerkamoBrowserClient, PerkamoProvider } from "@perkamo/react";

const client = createPerkamoBrowserClient({ getToken });

<PerkamoProvider client={client}>{children}</PerkamoProvider>;

Hooks

• usePerkamo() — the underlying PerkamoBrowserClient for emit() and direct calls.
• usePerkamoCustomer() — full customer profile with loading, error, refresh().
• usePerkamoCustomerJson(options?) — privacy-safe customer JSON view; traits are omitted unless includeTraits: true.
• usePerkamoCustomerStream() — live customer updates over SSE. Requires getStreamToken or streamTokenEndpoint on the provider.

Emitting events

const perkamo = usePerkamo();
await perkamo.emit("article.read", { category: "sdk" });

Documentation

See https://www.perkamo.com/docs for the full developer guide.