Alien Mini Apps React SDK: Overview and Installation

The @alien-id/miniapps-react package provides React hooks for building mini apps. It wraps the low-level bridge with React-friendly state management, so most apps never touch the bridge directly.

New in 2.1? Upgrading from an earlier release? Read Upgrade to v2 — supported is now callable, useIsMethodSupported is now useCallable, and capability checks return a typed reason instead of a bare boolean.

Install the React SDK

npm install @alien-id/miniapps-react

The React package also re-exports the bridge essentials so you rarely need a second import: send, request, callability, the bridge error classes, and the contract types — plus createMockBridge for testing. Utilities like isBridgeAvailable(), getLaunchParams(), and mockLaunchParamsForDev() live in @alien-id/miniapps-bridge.

Wrap Your App with AlienProvider

AlienProvider is the only required setup. Wrap your tree once at the root:

 
function App() {
  return (
    <AlienProvider>
      <YourApp />
    </AlienProvider>
  );
}

The provider initializes the bridge connection, reads launch parameters, sets safe-area CSS variables, and sends app:ready to the host app so it reveals your mini app. See App Lifecycle for why app:ready matters.

Set autoReady={false} to defer the ready signal until your initial data has loaded.

Read Context and Launch Params

useAlien

The core context: the auth token, the host’s protocol version, and whether the bridge is live.

 
const { authToken, contractVersion, isBridgeAvailable, ready } = useAlien();

The ready function is only needed when autoReady={false}.

useLaunchParams

Everything the host injected at launch. Returns undefined when launch params are unavailable (e.g. a plain browser tab).

 
const params = useLaunchParams();

DisplayMode values: 'standard' (default), 'fullscreen', 'immersive'.

Talk to the Host

Two primitives cover most host communication: useMethod for request-response calls and useEvent for one-way notifications.

useMethod

A generic hook for any request-response method. It handles loading and error state and gates the call on host support automatically.

 
const { execute, data, error, isLoading, reset, callable } = useMethod(
  'payment:request',
  'payment:response',
);
 
const { data, error } = await execute({
  recipient: 'wallet-address',
  amount: '1000000',
  token: 'USDC',
  network: 'solana',
  invoice: 'order-123',
});

useMethod takes exactly two arguments — the method and its response event. Version gating is always on: if the host can’t run the method, execute() skips the bridge call and writes a typed BridgeError to error (no loading flicker). To override the version a single call gates against, pass it to execute:

await execute(params, { version: '1.5.0' });

execute’s second argument is a SafeRequestOptions: { reqId?, timeout?, version? }.

useEvent

Subscribe to events from the host. Cleanup is automatic on unmount.

 
useEvent('host.back.button:clicked', () => {
  navigateBack();
});

Check Capability Before You Call

Hosts run different app versions, and your mini app may also be open in a plain browser. useCallable answers “can I call this method right now?” — and, when the answer is no, why.

 
const c = useCallable('payment:request');
 
if (c.callable) return <PayButton />;
if (c.reason === 'no-bridge') return <OpenInAlienApp />;
return <UpdateAlienApp needs={c.needs} has={c.has} />;

The result is a discriminated union, so TypeScript narrows each branch:

Every feature hook below also exposes a callable boolean built on this same check, so simple “show or hide” UI rarely needs useCallable directly.

Feature Hooks

Each feature has a dedicated hook and a dedicated page:

• usePayment — accept payments with full state management
• useClipboard — read and write the system clipboard
• useHaptic — trigger native haptic feedback
• useBackButton — control the host’s native back button
• useClose — close the mini app
• useNotificationPermission — request permission and send push notifications
• useLinkInterceptor — route external links through the host

 
const { pay, isPaid, isLoading, txHash, errorCode } = usePayment();
const { writeText, readText, callable } = useClipboard();
const { impactOccurred, notificationOccurred } = useHaptic();
const { close } = useClose();

All Hooks

supported → callable. Every call hook used to return supported. It still works as a deprecated alias for callable (and logs a one-time dev warning), but new code should use callable. See Upgrade to v2.

Next Steps

• App Lifecycle — app:ready, back button, closing
• Safe Area Insets — handle notches and home indicators
• Authentication — verify users on your backend
• Payments — accept payments
• Clipboard — system clipboard access
• Haptic Feedback — haptic feedback
• Notifications — request permission and send push notifications
• Link Management — open URLs through the host app
• Bridge Reference — the low-level bridge API