ailoha.
Home/ Docs/ React Native

Manual setup — React Native

Native HTTP servers (Swift on iOS, Kotlin on Android) handle requests, with a bidirectional JS bridge for the fiber tree, navigation, and console/network capture.

Package @ailoha/react-native Default port 9233 RN ≥ 0.73 Sample react-native/samples/AilohaSampleRN
i
Using Expo? See the Expo setup guide instead — the agent is the same package, but the prebuild flow is different.

Prerequisites

  • A bare React Native app on RN 0.73 or newer (TurboModules / new architecture is supported).
  • The Ailoha CLI installed: see install instructions.

1. Install the package

npm install @ailoha/react-native
# or
yarn add @ailoha/react-native

iOS pods

cd ios && pod install

The agent's native module is auto-linked. If autolinking doesn't pick it up, add it to your Podfile manually:

pod 'ailoha-react-native-agent', :path => '../node_modules/@ailoha/react-native'

Android linking

The agent registers via AgentPackage. If autolinking misses it, add to MainApplication.kt:

import com.ailoha.agent.AgentPackage

// In getPackages():
packages.apply {
    add(AgentPackage())
}

2. Initialize the agent

In App.tsx, gate the call behind __DEV__:

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

// Expose navigation ref so /ui/actions/navigate can drive React Navigation
const navigationRef = createNavigationContainerRef();
(global as any).__reactNavigationRef = navigationRef;

export default function App() {
  useEffect(() => {
    if (__DEV__) {
      try {
        const { initAgent } = require('@ailoha/react-native');
        initAgent({ port: 9233 });
      } catch (e: any) {
        console.error('Failed to init agent:', e?.message);
      }
    }
  }, []);

  return (
    <NavigationContainer ref={navigationRef}>
      {/* Your app */}
    </NavigationContainer>
  );
}
!
Use require() with a string literal inside try/catch — Metro rejects dynamic require(variable) calls. The wrapping __DEV__ guard tree-shakes the import out of release bundles.

3. Configure (optional)

initAgent({
  port: 9233,                   // default 9233
  enableNetworkCapture: true,   // intercept fetch/XMLHttpRequest
  enableLogCapture: true,       // capture console.log
  enableProfiler: true,         // JS profiler
});

4. Use stable test IDs

The agent uses testID as the canonical element ID:

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

5. Run and verify

Start the dev build (npm run ios or npm run android), then check the agent:

ailoha agent status
ailoha ui tree --depth 2

For Android emulators or physical devices, forward the port:

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

Troubleshooting

  • Native module not found. Re-run pod install on iOS or do a clean Gradle build on Android. Restart Metro with --reset-cache.
  • Port collision on shared CI runners. Prefer broker discovery; set a unique initAgent({ port: ... }) override only when you intentionally run multiple local agents.
  • Navigation actions don't work. Make sure global.__reactNavigationRef is set before React Navigation mounts.
  • Local file: dependency. If you symlink the agent for development, add a watchFolders entry to metro.config.js so Metro can resolve it.

What's next