@calimero-network/mero-react

React bindings for Calimero 1.0, on the mero-js 28 client (CalimeroClient).

A 1.0 node runs in an attested TDX cluster. The client verifies the node's attestation, seals every request to the node's attested key, and signs people in with passkeys. mero-react puts one client in context and builds the hooks on top of it:

• passkey sign-in and sign-up;
• sessions that refresh by themselves;
• calls, views and live events on an app instance;
• organizations, teams and invites;
• the node's consent page for approvals;
• blobs and presence;
• typed errors your UI can switch on.

Upgrading from 10.x? 11.0 is a rewrite for core 1.0, which removed /admin-api, /jsonrpc, /ws, /sse, mero-auth and /auth/token. Read Migrating from 10.x below.

Installation

pnpm add @calimero-network/mero-react

@calimero-network/mero-js (^28.0) comes with it, and every mero-js export is re-exported, so apps need only this import. React 18 or 19 is a peer dependency.

Quick start

import {
  MeroProvider,
  ConnectButton,
  useMero,
  useView,
  useExecute,
  useSubscription,
} from '@calimero-network/mero-react';

export function Root() {
  return (
    // A frontend the node serves at {label}.{apps-domain}:
    <MeroProvider servedByNode minReleaseVersion="2.3.109" appId={APP_ID}>
      <App />
    </MeroProvider>
  );
}

function App() {
  const { isAuthenticated } = useMero();
  const items = useView<string[]>('list_items');
  const { execute, failure } = useExecute();
  useSubscription(undefined, (event) => {
    if (event.kind === 'ItemAdded') void items.refetch();
  });

  if (!isAuthenticated) return <ConnectButton appName="Notes" />;
  return (
    <>
      <ul>{items.data?.map((item) => <li key={item}>{item}</li>)}</ul>
      <button onClick={() => execute('add_item', { text: 'hello' })}>Add</button>
      {failure && <p role="alert">{failure.message}</p>}
    </>
  );
}

A frontend hosted elsewhere reaches a Calimero Cloud cluster by name, failing over between its nodes:

<MeroProvider cluster="eu-shared-1" minReleaseVersion="2.3.109" appId={APP_ID}>

For local development against merod local (three --dev nodes with mock attestation on 127.0.0.1:2501-2503):

<MeroProvider
  nodeUrl="http://127.0.0.1:2501"
  nodes={['http://127.0.0.1:2502', 'http://127.0.0.1:2503']}
  allowMock
>

allowMock accepts mock attestation quotes. Never set it from anything a visitor controls, such as a URL parameter or the environment of a deployed build.

<MeroProvider>

useMero()

const {
  client,            // CalimeroClient | null (null until a node is known, or a cluster's nodes are)
  nodeUrl,           // the node in use
  cluster,           // the cluster connected to by name, or null
  isConnecting,      // the node directory is being read
  connectToNode,     // (url) => void
  connectToCluster,  // (name) => void
  disconnect,
  session, accountId, isAuthenticated, isLoading,
  signIn,            // () => Promise<CalimeroSession | null>: an existing passkey
  signUp,            // (name) => Promise<CalimeroSession | null>: a new account and passkey
  signOut, signOutEverywhere,
  appId, setAppId,
  passkey, servedByNode, allowMock,
  failure,           // the last sign-in, connection or session failure, described
  reportError,
} = useMero();

Sessions. A 1.0 session is a session token (v2.…) that lasts 15 minutes, plus a refresh token (rt_…) that lasts 30 days and can be used once.

• The client refreshes by itself on a 401. One refresh is shared by every request waiting on it, because reusing a refresh token revokes the session. When the node that issued the session is gone, the refresh goes to another node of the cluster (mero-js#318).
• The provider saves every new session to sessionStore, so a reload resumes the session.
• When a refresh is refused, hooks get LoginRequired, and the provider ends the session and sets failure.kind = 'login'.
• mero is still on the value as a deprecated alias of client.

Hooks

Every read hook returns { data, loading, error, failure, refetch }. Every action hook returns its action plus { loading, error, failure }.

• error is the error exactly as the client threw it, so instanceof AppError still works.
• failure is describeError(error); see Errors.
• An action resolves null when it fails. Pass { throwOnError: true } to make it throw instead.

App: calls, views, events

appId defaults to the provider's appId.

How useSubscription behaves:

• Each app gets one SSE stream with an AbortController. Unmounting, or changing the app ids, aborts it.
• A stream that ends or fails reopens with backoff from the last event it saw. Events at or before that one are skipped, so nothing is delivered twice.
• from defaults to 'live'. Pass a log index to replay from it (0 replays the whole history).
• onOpen is called each time a stream opens. Refetch views there to cover a gap.

Apps

Organizations and teams

Passkey step-ups. Since mero-js 28 the node approves membership changes, capabilities, invites, passkeys and API keys with the caller's passkey: it answers 412 CONFIRM_REQUIRED and the client answers that with the provider's passkey (browserPasskey() by default), so the person sees a passkey prompt. A dismissed prompt fails the action with failure.kind = 'cancelled'.

Invites

inviteLink(token, base?) and readInviteToken(href) are exported too.

Consent page

Approvals happen only on the page the node serves on its own origin, never inside an app. A session opened on an app's frontend cannot approve anything.

const consent = useConsent();
await consent.open(upgradeConsent(appId, '1.2.0', window.location.href), {
  // Show the confirmation code before leaving; the node's page shows the same one.
  confirm: (started) => window.confirm(`The approval page will show the code ${started.code}. Continue?`),
}); // then navigates to the node's page
// … back on returnTo:
if (consent.returned) await consent.check(consent.returned.requestId);    // confirm the hint
// or, when the page was opened in another window:
await consent.wait(started.requestId);

useConsent() returns { request, open, check, wait, cancel, started, code, result, returned, … }. code is the confirmation code (XXX-XXX) the consent page shows for the request under way: show it next to the link or in open's confirm, so the person can check they landed on the page their request opened. open throws CONSENT_CODE_MISMATCH when the node's code does not match the request (mero-js confirmationCode). Build requests with mero-js releaseConsent, withdrawConsent and upgradeConsent.

Blobs, presence, account

Errors

mero-js maps every refusal to a typed error (errorFrom, mero-js#312). mero-react keeps that error in error and adds failure = describeError(error):

type Failure = {
  kind: FailureKind;          // see the table
  message: string;            // a sentence you can show as it is
  retryable: boolean;
  status?: number; code?: string;
  appCode?: string; fields?: Record<string, unknown>;   // kind 'app'
  committed?: false | 'unknown';                         // kind 'unavailable'
  release?: string;                                      // kind 'release-deadline'
  error: unknown;
};

Components

• <ConnectButton appName? allowSignUp? initialTab? theme? logoOnly? label? />. Signed out, it shows "Sign in" and opens LoginModal. Signed in, it shows the account, with a menu for Sign out and Sign out everywhere.
• <LoginModal isOpen onClose onSignedIn? initialTab? allowSignUp? appName? theme? />. Sign in with a passkey, or create an account, which asks for a name. Off a node-served page it asks first for the node URL or a cluster name.

Theming

Pass a partial MeroTheme (primary, primaryHover, primaryText, background, backgroundSecondary, backgroundTertiary, border, text, textSecondary, error, overlay, radius), or set the --mero-* CSS variables globally:

:root {
  --mero-accent: #ff4081;
  --mero-accent-hover: #e91e63;
}

The dialog's classes are mero-dialog-overlay, mero-dialog-panel, mero-dialog-title, mero-dialog-body, mero-dialog-field, mero-dialog-input, mero-dialog-button, mero-dialog-primary, mero-dialog-secondary and mero-dialog-link. The button's classes are mero-connect-button, mero-dropdown and mero-dropdown-item.

Storage

• localStorageSessionStore and memorySessionStore(): session stores.
• getNodeUrl / setNodeUrl / clearNodeUrl, getCluster / setCluster / clearCluster and getAppId / setAppId / clearAppId.
• clearAllStorage() clears all of the above.
• Keys: mero:session, mero:nodeUrl, mero:cluster, mero:appId. 10.x tokens are not read.

Migrating from 10.x

core 1.0 is a different node, and mero-js 28 is a different client, so 11.0 is a breaking release. Most app ports are mechanical:

1. Provider.
   • Drop mode, packageName, packageVersion, registryUrl, cloudBaseUrl, timeoutMs, allowedNodeUrls and tokenStore.
   • Add minReleaseVersion (production) or allowMock (merod local).
   • Keep servedByNode. Pass appId if the app works on one instance.
2. Client.
   • useMero().mero (a MeroJs or relay client) is now useMero().client (a CalimeroClient).
   • mero.rpc.execute({ contextId, method, argsJson, executorPublicKey }) is now client.call(appId, method, args), or client.view(…) for reads.
3. Vocabulary.
   • context is now app instance (appId);
   • namespace is now organization;
   • group is now team;
   • executor / node identity is now the signed-in account.
4. Auth.
   • There is no redirect, callback or access_token in the URL any more.
   • connectToNode(url) only picks the node. Signing in is signIn() or signUp(name) (passkeys), or <ConnectButton />.
5. Errors. Switch on failure.kind, or instanceof AppError / ConfirmRequired / WrongNode, instead of HTTP status checks.

Removed with no replacement (v1 or desktop only):

• admin-API hooks: useSyncGroup, useResyncContext, useJoinSubgroupInheritance, useDetachContextFromGroup, useSetTeeAdmissionPolicy, useContextDiscovery;
• migration hooks and components: useMigrationStatus, useMigrationEvents, useMyAuthoredMigration, MigrationPendingBanner, MigrationAdminPanel;
• version hooks: useAppVersion, useLatestVersion, useGroupAppVersion;
• the delegated / relay / account-enrolment layer: useAccountEnrolment, useDelegatedBootstrap, ConnectButtonAccount, AccountSignInPanel, and the relay, joinWithNode and bootstrapFromInvitation re-exports;
• invitation UI: InvitationGate, InvitationDialog, JoinSyncBanner, useJoinSync;
• local-node discovery: discoverLocalNodes;
• desktop (Tauri): isDesktopWindow.

License

MIT