ailoha.
Home/ Docs/ Expo

Manual setup — Expo

The Ailoha React Native native module autolinks during expo prebuild and works in custom dev clients and EAS development builds.

Package @ailoha/react-native Default port 9233 Expo SDK ≥ 50 Sample react-native/samples/AilohaSampleExpo
!
The agent runs native code, so it does not work in Expo Go. You need a custom dev client (expo prebuild + expo run:ios / expo run:android) or an EAS dev build.

Prerequisites

  • An Expo SDK 50+ project using the bare workflow or with prebuild enabled.
  • expo-dev-client installed (so you can run a custom client instead of Expo Go).
  • The Ailoha CLI installed: see install instructions.

1. Install the package

npx expo install expo-dev-client @ailoha/react-native

The package is consumed as a React Native native module. Do not add it to expo.plugins; Expo prebuild picks it up through native autolinking.

2. Prebuild and run a dev client

npx expo prebuild
npx expo run:ios
# or
npx expo run:android

If you maintain a managed project and don't want to commit native folders, prebuild on demand or use EAS:

eas build --profile development --platform ios
eas build --profile development --platform android

3. Initialize the agent

In App.tsx (or your entry component), gate the call behind __DEV__:

import React, { useEffect } from 'react';
import { NavigationContainer, createNavigationContainerRef } from '@react-navigation/native';

const navigationRef = createNavigationContainerRef();
(global as any).__reactNavigationRef = navigationRef;

function initializeAgent(): void {
  if (!__DEV__) return;
  try {
    const { initAgent } = require('@ailoha/react-native');
    initAgent({ port: 9233 });
  } catch (e: any) {
    console.error('[Ailoha] Failed to init agent:', e?.message);
  }
}

export default function App() {
  useEffect(() => { initializeAgent(); }, []);

  return (
    <NavigationContainer ref={navigationRef}>
      {/* Your app */}
    </NavigationContainer>
  );
}

4. Configure (optional)

initAgent({
  port: 9233,
  enableNetworkCapture: true,
  enableLogCapture: true,
  enableProfiler: true,
});

5. Use stable test IDs

<Pressable testID="login-button" onPress={signIn}>
  <Text>Sign in</Text>
</Pressable>

6. Run and verify

ailoha agent status
ailoha ui tree --depth 2

On Android emulators or devices:

adb forward tcp:9233 tcp:9233
curl http://localhost:9233/api/v1/agent/status

Troubleshooting

  • Stuck on Expo Go. The agent needs native code. Switch to a dev client or EAS build.
  • Module not autolinked after prebuild. Re-run npx expo prebuild --clean and rebuild.
  • EAS release builds bundle the agent. Confirm the initAgent call is gated by __DEV__; release builds will tree-shake the import out.
  • Port collision. Prefer broker discovery; set a unique initAgent({ port: ... }) override only when you intentionally run multiple local agents.

What's next