React Native

This guide covers React Native-specific features of the Jade SDK, including storage adapters and app state handling.

For a complete working example, see the React Native example app with chat UI, media gallery, and custom tool UIs.

Storage Adapters

The React Native SDK requires a storage adapter for persisting data like session state, authentication tokens, and preferences.

AsyncStorage Adapter

The most common storage solution using @react-native-async-storage/async-storage:

import { JadeProvider, createAsyncStorageAdapter } from '@gr33n-ai/jade-sdk-rn-client';
import AsyncStorage from '@react-native-async-storage/async-storage';

const storage = createAsyncStorageAdapter(AsyncStorage);

export default function App() {
  return (
    <JadeProvider
      config={{
        endpoint: 'https://api.gr33n.ai',
        getAuthToken: async () => await AsyncStorage.getItem('@gr33n-ai/api-key'),
      }}
      storage={storage}
    >
      <Navigation />
    </JadeProvider>
  );
}

Custom Storage Adapter

Implement your own storage adapter for alternative storage solutions:

interface StorageAdapter {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
}

Example with MMKV for better performance:

import { MMKV } from 'react-native-mmkv';

const mmkv = new MMKV();

const mmkvStorage: StorageAdapter = {
  getItem: async (key) => {
    const value = mmkv.getString(key);
    return value ?? null;
  },
  setItem: async (key, value) => {
    mmkv.set(key, value);
  },
  removeItem: async (key) => {
    mmkv.delete(key);
  },
};

<JadeProvider config={config} storage={mmkvStorage}>

Secure Storage with Keychain

For sensitive data like API keys:

import * as Keychain from 'react-native-keychain';

const keychainStorage: StorageAdapter = {
  getItem: async (key) => {
    try {
      const credentials = await Keychain.getGenericPassword({ service: key });
      return credentials ? credentials.password : null;
    } catch {
      return null;
    }
  },
  setItem: async (key, value) => {
    await Keychain.setGenericPassword(key, value, { service: key });
  },
  removeItem: async (key) => {
    await Keychain.resetGenericPassword({ service: key });
  },
};

Storage Keys

The SDK uses these predefined storage keys:

const STORAGE_KEYS = {
  AUTH_TOKEN: '@gr33n-ai/auth-token',
  ENDPOINT: '@gr33n-ai/endpoint',
  ORG_ID: '@gr33n-ai/org-id',
  LAST_SESSION_ID: '@gr33n-ai/last-session-id',
  USER_PREFERENCES: '@gr33n-ai/user-preferences',
} as const;

Import and use these keys:

import { STORAGE_KEYS } from '@gr33n-ai/jade-sdk-rn-client';

// Save session for recovery
await storage.setItem(STORAGE_KEYS.LAST_SESSION_ID, sessionId);

// Retrieve on app launch
const savedSession = await storage.getItem(STORAGE_KEYS.LAST_SESSION_ID);

Accessing Storage in Components

Use the useStorage hook to access the storage adapter:

import { useStorage } from '@gr33n-ai/jade-sdk-rn-client';

function Settings() {
  const storage = useStorage();

  const savePreference = async (key: string, value: string) => {
    if (storage) {
      await storage.setItem(`@preferences/${key}`, value);
    }
  };

  // ...
}

App State Handling

React Native apps transition between foreground and background states. The Jade SDK handles these transitions automatically.

Default Behavior

By default, the SDK:

Pauses streaming when the app goes to background
Maintains connection state for reconnection
Resumes automatically when the app returns to foreground

<JadeProvider
  config={config}
  storage={storage}
  pauseOnBackground={true}  // Default: true
>

useAppState Hook

Monitor app state in your components:

import { useAppState } from '@gr33n-ai/jade-sdk-rn-client';

function StreamingIndicator() {
  const appState = useAppState();

  if (appState === 'background') {
    return <Text>Streaming paused</Text>;
  }

  if (appState === 'inactive') {
    return <Text>Transitioning...</Text>;
  }

  return <Text>Active</Text>;
}

App State Values

Value	Description
`'active'`	App is in the foreground and interactive
`'background'`	App is in the background
`'inactive'`	App is transitioning (iOS only)

Conditional UI

Show different UI based on app state:

function Chat() {
  const appState = useAppState();
  const { isStreaming } = useJadeSession();

  return (
    <View>
      {appState !== 'active' && isStreaming && (
        <Banner type="warning">
          Generation paused while app is in background
        </Banner>
      )}

      <ConversationList />
      <InputBar />
    </View>
  );
}

Disable Background Pause

For apps that need to continue streaming in the background:

<JadeProvider
  config={config}
  storage={storage}
  pauseOnBackground={false}
>

Streaming in the background consumes battery and may be terminated by the OS. Consider using push notifications for long-running operations instead.

Manual Reconnection

Handle reconnection manually for more control:

import { useEffect, useRef } from 'react';
import { useAppState, useJadeSession } from '@gr33n-ai/jade-sdk-rn-client';

function Chat() {
  const appState = useAppState();
  const { sessionId, reconnect, isStreaming } = useJadeSession();
  const wasStreamingRef = useRef(false);

  // Track if we were streaming before background
  useEffect(() => {
    if (appState === 'background' && isStreaming) {
      wasStreamingRef.current = true;
    }
  }, [appState, isStreaming]);

  // Reconnect when returning to foreground
  useEffect(() => {
    if (appState === 'active' && wasStreamingRef.current && sessionId) {
      wasStreamingRef.current = false;
      reconnect(sessionId);
    }
  }, [appState, sessionId]);

  // ...
}

Session Recovery

Recover session state after app restart:

import { useEffect, useState } from 'react';
import { useJadeSession, useJadeClient, STORAGE_KEYS } from '@gr33n-ai/jade-sdk-rn-client';
import AsyncStorage from '@react-native-async-storage/async-storage';

function Chat() {
  const [isRestoring, setIsRestoring] = useState(true);
  const client = useJadeClient();
  const { loadSession, reconnect } = useJadeSession();

  useEffect(() => {
    const restore = async () => {
      try {
        const sessionId = await AsyncStorage.getItem(STORAGE_KEYS.LAST_SESSION_ID);
        if (sessionId) {
          // Check if session was streaming
          const { streaming } = await client.getSessionStatus(sessionId);

          if (streaming) {
            // Reconnect to active stream
            await reconnect(sessionId);
          } else {
            // Load completed conversation
            await loadSession(sessionId);
          }
        }
      } catch (e) {
        console.error('Failed to restore session:', e);
      } finally {
        setIsRestoring(false);
      }
    };

    restore();
  }, []);

  if (isRestoring) {
    return <LoadingScreen />;
  }

  return <ChatInterface />;
}

Background Execution

iOS Background Modes

For iOS, if you need limited background execution, configure in Info.plist:

<key>UIBackgroundModes</key>
<array>
  <string>fetch</string>
</array>

Background execution is limited on iOS. For long-running tasks, consider using server-side processing with push notifications.

Android Keep-Alive

For Android apps that need to stay alive:

import { AppState, Platform } from 'react-native';
import notifee from '@notifee/react-native';

function useBackgroundKeepAlive() {
  useEffect(() => {
    if (Platform.OS !== 'android') return;

    const subscription = AppState.addEventListener('change', async (state) => {
      if (state === 'background') {
        // Show foreground service notification
        await notifee.displayNotification({
          title: 'Jade',
          body: 'Generating media...',
          android: {
            channelId: 'foreground',
            asForegroundService: true,
          },
        });
      } else if (state === 'active') {
        // Remove notification
        await notifee.cancelAllNotifications();
      }
    });

    return () => subscription.remove();
  }, []);
}

SSE Streaming

The React Native SDK uses react-native-sse for Server-Sent Events, which is bundled automatically. No additional configuration is required.

Differences from Web

Feature	Web	React Native
SSE Library	Native `EventSource`	`react-native-sse`
Client Class	`AgentClient`	`JadeClient`
Client Hook	`useAgentClient`	`useJadeClient`
Storage	`localStorage`	`StorageAdapter`
App State	N/A	`useAppState`
Background Pause	N/A	`pauseOnBackground`

Streaming State

The useJadeSession hook provides detailed streaming state for building rich UIs:

const {
  // Core streaming
  isStreaming,             // Whether AI is responding
  streamingText,           // Text being streamed (live updates)

  // Tool execution
  streamingToolCall,       // Tool call being streamed (name, input)
  isExecutingTool,         // Whether a tool is currently executing
  executingToolName,       // Name of the tool being executed (e.g., "generative_image")

  // UI hints
  showTinkering,           // Show "thinking" indicator before first content
} = useJadeSession();

Building a Tool Execution UI

function StreamingIndicator() {
  const { isStreaming, showTinkering, isExecutingTool, executingToolName } = useJadeSession();

  if (!isStreaming) return null;

  if (showTinkering) {
    return <Text>Thinking...</Text>;
  }

  if (isExecutingTool) {
    return (
      <View style={styles.toolIndicator}>
        <ActivityIndicator size="small" />
        <Text>Generating with {executingToolName}...</Text>
      </View>
    );
  }

  return null;
}

Complete Example

import { useState, useEffect } from 'react';
import {
  View,
  Text,
  TextInput,
  FlatList,
  ActivityIndicator,
} from 'react-native';
import { SafeAreaView } from 'react-native-safe-area-context';
import {
  JadeProvider,
  useJadeSession,
  useAppState,
  useJadeClient,
  createAsyncStorageAdapter,
  STORAGE_KEYS,
} from '@gr33n-ai/jade-sdk-rn-client';
import AsyncStorage from '@react-native-async-storage/async-storage';

const storage = createAsyncStorageAdapter(AsyncStorage);

function ChatScreen() {
  const appState = useAppState();
  const client = useJadeClient();
  const { processedConversation, isStreaming, sendMessage, sessionId, reconnect, loadSession } = useJadeSession();
  const [isRestoring, setIsRestoring] = useState(true);

  // Restore session on mount
  useEffect(() => {
    const restore = async () => {
      try {
        const savedId = await AsyncStorage.getItem(STORAGE_KEYS.LAST_SESSION_ID);
        if (savedId) {
          const { streaming } = await client.getSessionStatus(savedId);
          if (streaming) {
            await reconnect(savedId);
          } else {
            await loadSession(savedId);
          }
        }
      } finally {
        setIsRestoring(false);
      }
    };
    restore();
  }, []);

  // Save session ID when it changes
  useEffect(() => {
    if (sessionId) {
      AsyncStorage.setItem(STORAGE_KEYS.LAST_SESSION_ID, sessionId);
    }
  }, [sessionId]);

  if (isRestoring) {
    return (
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <ActivityIndicator size="large" />
        <Text>Restoring session...</Text>
      </View>
    );
  }

  return (
    <SafeAreaView style={{ flex: 1 }}>
      {appState !== 'active' && isStreaming && (
        <View style={{ padding: 8, backgroundColor: '#fef3c7' }}>
          <Text>⏸️ Generation paused (app in background)</Text>
        </View>
      )}

      <FlatList
        data={processedConversation}
        keyExtractor={(_, i) => i.toString()}
        renderItem={({ item }) => (
          <View style={{ padding: 12, marginVertical: 4 }}>
            <Text style={{ fontWeight: 'bold' }}>
              {item.originalType === 'user_text' ? 'You' : 'Jade'}
            </Text>
            <Text>{item.entry.text}</Text>
          </View>
        )}
      />

      {/* Input form would go here */}
    </SafeAreaView>
  );
}

export default function App() {
  return (
    <JadeProvider
      config={{
        endpoint: 'https://api.gr33n.ai',
        getAuthToken: async () => await AsyncStorage.getItem('@gr33n-ai/api-key'),
      }}
      storage={storage}
      pauseOnBackground={true}
    >
      <ChatScreen />
    </JadeProvider>
  );
}

Best Practices

Use AsyncStorage or MMKV for general data persistence

Use Keychain for sensitive data like API keys

Let the SDK handle background pausing automatically

Show clear UI when streaming is paused

Persist session ID for recovery after app termination

Check session status before reconnecting

Use push notifications for long-running operations

Test background/foreground transitions thoroughly

JadeProvider - Provider configuration
Hooks Reference - All available hooks
Session Management - Session persistence patterns

Getting Started

Guides

Integration

Examples

Storage Adapters

AsyncStorage Adapter

Custom Storage Adapter

Secure Storage with Keychain

Storage Keys

Accessing Storage in Components

App State Handling

Default Behavior

useAppState Hook

App State Values

Conditional UI

Disable Background Pause

Manual Reconnection

Session Recovery

Background Execution

iOS Background Modes

Android Keep-Alive

SSE Streaming

Differences from Web

Streaming State

Building a Tool Execution UI

Complete Example

Best Practices

​Storage Adapters

​AsyncStorage Adapter

​Custom Storage Adapter

​Secure Storage with Keychain

​Storage Keys

​Accessing Storage in Components

​App State Handling

​Default Behavior

​useAppState Hook

​App State Values

​Conditional UI

​Disable Background Pause

​Manual Reconnection

​Session Recovery

​Background Execution

​iOS Background Modes

​Android Keep-Alive

​SSE Streaming

​Differences from Web

​Streaming State

​Building a Tool Execution UI

​Complete Example

​Best Practices

​Related

Storage Adapters

AsyncStorage Adapter

Custom Storage Adapter

Secure Storage with Keychain

Storage Keys

Accessing Storage in Components

App State Handling

Default Behavior

useAppState Hook

App State Values

Conditional UI

Disable Background Pause

Manual Reconnection

Session Recovery

Background Execution

iOS Background Modes

Android Keep-Alive

SSE Streaming

Differences from Web

Streaming State

Building a Tool Execution UI

Complete Example

Best Practices

Related