SDK Overview
This page covers the React Native SDK. For web apps (React, Vue, Svelte, or vanilla), see the Web SDK.
@appilots/sdk is a React Native package that embeds an AI chat UI in your app and gives an AI agent the ability to navigate screens, read what's on them, and operate them — pressing buttons, filling forms, flipping switches — on the user's behalf.
This page covers installation, the package's export surface, and the optional Metro plugin. For the actual wiring, continue to AppilotsProvider and AppilotsChat.
Requirements
@appilots/sdk declares these as peer dependencies — install them if your app doesn't already have them:
| Package | Minimum version |
|---|---|
react | >=18.0.0 |
react-native | >=0.72.0 |
react-native-safe-area-context | >=4.0.0 |
react-native-svg | >=13.0.0 |
Installation
npm install @appilots/sdk
yarn add @appilots/sdk
pnpm add @appilots/sdk
Metro plugin (recommended)
The SDK ships a Metro plugin that auto-loads your .appilotsrc file at bundle time. With it configured, AppilotsProvider needs zero props — no projectId or apiKey hardcoded in your app code.
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const { withAppilots } = require('@appilots/sdk/metro');
const config = {};
module.exports = withAppilots(mergeConfig(getDefaultConfig(__dirname), config));
The plugin is half the wiring. The other half is one import in your entry file, and the app does not work without it:
import '@appilots/auto-init'; // must be the first import
import { AppRegistry } from 'react-native';
import App from './App';
import { name as appName } from './app.json';
AppRegistry.registerComponent(appName, () => App);
withAppilots() does not inject anything into your bundle. At Metro startup it
reads .appilotsrc and generates a module under
node_modules/.cache/appilots/, then registers a resolver so that
@appilots/auto-init points at it. Nothing imports that module for you — so if
your entry file has no import '@appilots/auto-init', the generated module
never enters the bundle, global.__APPILOTS_RC__ is never set, and
AppilotsProvider throws
"No config found" at
runtime even though your .appilotsrc and metro.config.js are both correct.
It has to be the first import: the generated module calls initAppilots(),
which patches React.createElement and the JSX runtimes for auto-tracking, and
that must happen before any app component renders.
Wrap the merged config, as above — withAppilots() reads projectRoot off
the config you hand it to locate .appilotsrc. Passing it a bare {} and
merging afterwards leaves it falling back to process.cwd(), which works only
while Metro is started from the project root.
See CLI configuration for the .appilotsrc file format. If you skip the Metro plugin, pass config explicitly to AppilotsProvider instead — both paths are covered in AppilotsProvider.
withAppilots() also sets keep_fnames / keep_classnames in the Metro
minifier config. Several React Native components (Switch, Modal, FlatList,
SectionList, VirtualizedList) declare no displayName, so a minifier that
renames them makes the SDK fall back to coarser detection. Your own
minifierConfig wins on every key it sets, so a project that deliberately
mangles names keeps doing so.
This only matters if your build minifies at all: with Hermes on (the default
since React Native 0.70) the CLI's release build does not. Detection is designed
to work either way — accessibility roles, the native modal host and the list
props signature carry it — and if names do get mangled the SDK reports it as
names-mangled in its introspection diagnostics instead of degrading silently.
Package exports
The main entry point (@appilots/sdk) re-exports everything the SDK has to offer. Two narrower subpaths exist for consumers who want a smaller import surface — they don't expose anything the root doesn't already have:
| Subpath | Contents |
|---|---|
@appilots/sdk | Everything below — the main entry point. |
@appilots/sdk/navigation | Just the navigation exports (AppilotsNavigationContainer, registerScreen, navigation types). |
@appilots/sdk/hooks | Just the hooks (useAppilots, useAppilotsField, etc). |
@appilots/sdk/metro | The Metro plugin (withAppilots), used from metro.config.js. |
Every subpath resolves from CommonJS and ESM alike. If your app's package.json
sets "type": "module", Metro treats metro.config.js as ESM — import the
plugin instead of requiring it, and keep the rest of the config the same:
import { withAppilots } from '@appilots/sdk/metro';
What's exported
| Group | Exports | Purpose |
|---|---|---|
| Provider | AppilotsProvider, useAppilotsContext, AppilotsConfig | Root context — see AppilotsProvider. |
| Chat | AppilotsChat and its prop types | The chat UI — see AppilotsChat. |
| Theming | AppilotsThemeProvider, useAppilotsTheme, defaultLightTheme, defaultDarkTheme, mergeThemeTokens, appilotsTheme, appilotsThemeFromTailwind | Token-based theming — see Theming. |
| i18n | AppilotsI18nProvider, useAppilotsI18n, detectDeviceLocale, resolveLocale | Locale detection and string bundles — see Customization: i18n. |
| UI pieces | ConfirmDialog, ActionBreadcrumb, ChatIcon, HeadsetIcon | Standalone components you can reuse in a custom chat surface. |
| Hooks | useAppilots, useAppilotsNavigation, useAppilotsChat, useAppilotsActions, useAppilotsField, useAppilotsTarget, useAppilotsToggle, useAppilotsSlider, useSuggestedPrompts | Read/write access to chat state, navigation state, and the component registry — see Hooks and Registering elements. |
| Navigation | AppilotsNavigationContainer, registerScreen, ScreenMetadata, NavigationConfig | Screen-level metadata for the agent — see Navigation. |
| Registry | componentRegistry, elementRegistry, listRegistry, createComponentRegistry, createElementRegistry, createListRegistry, AppilotsRegistryProvider, useResolvedRegistry | The low-level registry that the hooks, HOCs, and auto-tracking all write into. Most apps never touch this directly — the singleton registry is used automatically unless you explicitly scope a subtree with AppilotsRegistryProvider. |
| Config loading | initAppilots, getGlobalConfig | Reads .appilotsrc at runtime (used by the Metro plugin path). |
| Auto-tracking | enableAppilotsAutoTracking, isAutoTrackingEnabled | Zero-config component registration — see Registering elements. |
| Runtime snapshot | captureSnapshot and its type exports | Internal runtime snapshot used to build the agent's context of the current screen. |
| Introspection health | getIntrospectionDiagnostics, IntrospectionDiagnostics | Whether the SDK could reach your React tree. captured: false means every snapshot this session is empty — see Troubleshooting. |
| HOC factories | createAppilotsInput, createAppilotsButton, createAppilotsSwitch | Wrap a shared component once so every usage auto-registers — see Registering elements. |
| Executor | executeAction, ExecutorContext, ActionResult | The low-level action executor that the hooks and auto-tracking build on. |
| HTTP client | AppilotsClient | The client the provider builds from your config — see API Reference for the wire contract. |
| Core types | AgentAction, AgentActionType, AgentMessage, AgentPermissions, ChatMessage, FormFillPayload, NavigationPayload, UIInteractionPayload, AppilotsEvent, AppilotsEventType, AppilotsEventHandler, AppilotsTraceEntry, EscalationState, MessageRole | Shared TypeScript types used across the public API. |
| Version | SDK_VERSION | The installed SDK version string. |
Next steps
- AppilotsProvider — wrap your app and configure the SDK.
- AppilotsChat — drop in the chat UI.
- Navigation — describe your screens to the agent.
- CLI overview — generate and sync the MCP document your project needs before the agent can do anything useful.