React SDK

@layers/amba-react wraps @layers/amba-web in reactive hooks that re-render when SDK state changes. Same imperative surface is still available through useAmba() for one-off calls — the hooks just add the missing reactivity layer.

Works with React 18 and React 19 (server components are not supported — every hook is a client hook).

1. Install

pnpm add @layers/amba-react @layers/amba-web react

react is a peer dependency; the package will use whichever React version your app has installed. @layers/amba-web is the underlying SDK — the hooks are a thin reactive layer over it.

2. Configure before render

Configure the underlying @layers/amba-web SDK before rendering <AmbaProvider>. The provider does not configure the SDK itself — it just plugs the React tree into the SDK's state-change channel.

// src/main.tsx (Vite)
import React from 'react';
import ReactDOM from 'react-dom/client';
import { Amba } from '@layers/amba-web';
import { AmbaProvider } from '@layers/amba-react';
import App from './App';
 
await Amba.configure({
  projectId: import.meta.env.VITE_AMBA_PROJECT_ID!,
  clientKey: import.meta.env.VITE_AMBA_CLIENT_KEY!,
});
 
ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <AmbaProvider>
      <App />
    </AmbaProvider>
  </React.StrictMode>,
);

For Next.js, do the configure call inside a client-side bootstrap component that mounts at the root and wraps children in <AmbaProvider>. Use NEXT_PUBLIC_AMBA_PROJECT_ID and NEXT_PUBLIC_AMBA_CLIENT_KEY in your .env.local.

3. First hook: useUser

import { useUser } from '@layers/amba-react';
 
function Header() {
  const { user, isAuthenticated, loading } = useUser();
 
  if (loading) return <Skeleton />;
  if (!isAuthenticated) return <button onClick={signIn}>Sign in</button>;
  return <span>{user?.display_name ?? user?.email}</span>;
}
 
async function signIn() {
  // Re-uses the underlying @layers/amba-web SDK; the hook re-renders
  // automatically once the session is established.
  const { Amba } = await import('@layers/amba-web');
  await Amba.auth.signInAnonymously();
}

4. First collection: useCollection

import { useCollection } from '@layers/amba-react';
 
type Todo = { id: string; title: string; done: boolean };
 
function TodoList() {
  const {
    data: todos,
    loading,
    error,
    refetch,
  } = useCollection<Todo>('todos', {
    order: [{ column: 'created_at', direction: 'desc' }],
    limit: 50,
  });
 
  if (loading) return <Spinner />;
  if (error) return <p>Failed to load todos: {error.message}</p>;
 
  return (
    <>
      <button onClick={refetch}>Refresh</button>
      <ul>
        {todos?.map((t) => (
          <li key={t.id}>{t.title}</li>
        ))}
      </ul>
    </>
  );
}

useCollection re-fetches on mount, on options change, and whenever the SDK auth state changes. response.next_cursor is exposed on the returned response for cursor pagination.

5. Flags and entitlements

import { useFlag, useVariant, useEntitlement } from '@layers/amba-react';
 
function NewOnboarding() {
  const flag = useFlag('new_onboarding'); // FlagAssignment | null
  const variant = useVariant('signup_copy'); // 'control' | 'short' | 'long' | null
  const isPro = useEntitlement('pro');
 
  // `useFlag(name)` returns the full assignment record (or null while loading
  // / when the flag is not assigned to this user). Read `.enabled` for the
  // boolean gate.
  if (!flag?.enabled) return <ClassicOnboarding />;
  return <NewFlow copy={variant ?? 'control'} pro={isPro} />;
}

useEntitlement defaults to false while loading — safe for paywall gating (no flash-of-pro-content).

6. Track on mount

For page-view tracking:

import { useTrackOnMount } from '@layers/amba-react';
 
export default function HomePage() {
  useTrackOnMount('page_viewed', { path: '/home' });
  return <main>...</main>;
}

The track call is fire-and-forget; failures are swallowed so a flaky network doesn't crash render.

All hooks at a glance

@layers/amba-react exports the hooks below. A resource hook returns { data, loading, error, refetch } plus the helpers listed.

Every hook calls the matching @layers/amba-web method, so the SDK reference for each namespace applies; the Notes column lists the hooks whose arguments differ from the SDK call. useDeepLinks().create posts to a client route the API does not have, so it fails; create deep links with the admin API or amba_tracked_links_create.

Core

Social

Lifecycle

Gamification and economy

Escape hatch: raw SDK

When you need something the hooks don't cover yet (e.g. storage.upload, ai.anthropic.messages.create, push.register), use useAmba():

import { useAmba } from '@layers/amba-react';
 
function UploadAvatar() {
  const Amba = useAmba();
  async function onFileChange(e: React.ChangeEvent<HTMLInputElement>) {
    const file = e.target.files?.[0];
    if (!file) return;
    const asset = await Amba.storage.upload({ bucket: 'avatars', file });
    console.log(asset.url);
  }
  return <input type="file" onChange={onFileChange} />;
}

useAmba() is just Amba from @layers/amba-web plus subscription to the version counter — so the component re-renders when the SDK's auth state changes.

Server components

Server components run before any client SDK is configured. Don't import @layers/amba-react (or @layers/amba-web) from server-only modules.

Common pitfalls

• Hook called outside <AmbaProvider> throws "hooks must be used inside <AmbaProvider>". Wrap the root.
• Amba.configure() not awaited before render causes hooks to throw "amba SDK not configured". Either await it before the first render, or render a <SDKLoading /> boundary that flips when Amba.appUserId is no longer undefined.
• Two copies of @layers/amba-web — useUser, useFlag, etc. all import the same singleton from @layers/amba-web. If pnpm why @layers/amba-web shows two copies, the hooks subscribe to one and your Amba.configure() call configures the other. Hoist with pnpm dedupe.

See also

• Web SDK — the underlying imperative surface.
• Client API reference — full method signatures available through useAmba().
• Code samples — same operations side-by-side with the other 7 SDKs.