React SDK

The @alien_org/react package provides React hooks for building mini apps. It wraps the low-level bridge API with React-friendly state management.

It also re-exports bridge utilities (send, request, isAvailable, createMockBridge, etc.) and contract types for convenience. See Bridge Reference for full details on the low-level API.

Installation

npm install @alien_org/react

Setup

Wrap your app with AlienProvider:

 
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. See App Lifecycle for details on why app:ready matters.

AlienProvider Props

Set autoReady={false} to defer the ready signal.

Hooks Reference

useAlien

Access the core context values.

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

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

useLaunchParams

Get all launch parameters.

 
const params = useLaunchParams();

Returns undefined if launch params are unavailable (e.g., running in a browser).

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

useEvent

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

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

useMethod

Generic hook for request-response bridge methods. Handles loading, error states, and version checking automatically.

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

Options (third argument):

When checkVersion is true and the method is unsupported, execute() sets error to a MethodNotSupportedError without making a bridge call.

Return values:

useBackButton

Control the host app’s native back button. The button is automatically hidden on unmount.

 
const { show, hide, isVisible, supported } = useBackButton(() => {
  navigate(-1);
});
 
useEffect(() => {
  show();
  return () => hide();
}, [show, hide]);

See App Lifecycle for more details.

usePayment

Specialized hook for payments with full state management. See Payments for full documentation.

 
const { pay, isPaid, isLoading, txHash, errorCode } = usePayment({
  onPaid: (txHash) => console.log('Paid!', txHash),
  onCancelled: () => console.log('Cancelled'),
  onFailed: (code) => console.log('Failed:', code),
});
 
await pay({
  recipient: 'wallet-address',
  amount: '10000',
  token: 'USDC',
  network: 'solana',
  invoice: 'order-123',
});

useClipboard

Read and write to the system clipboard via the host app. See Clipboard for full documentation.

 
const { writeText, readText, isReading, errorCode, supported } = useClipboard();

useHaptic

Trigger haptic feedback on the user’s device. All methods are fire-and-forget. See Haptic Feedback for full documentation.

 
const { impactOccurred, notificationOccurred, selectionChanged, supported } = useHaptic();
 
impactOccurred('medium');
notificationOccurred('success');
selectionChanged();

Impact styles: 'light', 'medium', 'heavy', 'soft', 'rigid'

Notification types: 'success', 'warning', 'error'

useIsMethodSupported

Check if a method is supported by the host app version.

 
const { supported, minVersion, contractVersion } = useIsMethodSupported(
  'payment:request',
);
 
if (!supported) {
  return <div>Update the Alien app (requires {minVersion})</div>;
}

useLinkInterceptor

Intercept external link clicks and route them through the host app. AlienProvider enables this by default. See Link Management for full documentation.

 
useLinkInterceptor({ openMode: 'external' });

Next Steps

• App Lifecycle — app:ready and back button
• Safe Area Insets — Handle notches and home indicators
• Authentication — User authentication
• Payments — Accept payments
• Clipboard — System clipboard access
• Haptic Feedback — Haptic feedback
• Link Management — Open URLs through the host app
• Bridge Reference — Low-level bridge API
• Create Mini App — Register your mini app
• Testing — Test your mini app