Documentation Index
Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
Use this file to discover all available pages before exploring further.
React Native project requirements
The library requires React Native 0.85.3+ with a react version that satisfies React Native’s declared peer dependency (^19.2.3 for react-native@0.85.3). Also requires Node ≥ 24.0.0 and npm ≥ 11.0.0.
| Platform | Minimum | Notes |
|---|
| iOS deployment target | 16.4 | Required by Expo SDK 56 (raised from 15.1 in 55). Set in ios/Podfile (platform :ios, '16.4'). |
Android minSdkVersion | 24 (Android 7.0) | Set in android/build.gradle. Required by RN 0.85. |
Android compileSdkVersion / targetSdkVersion | RN 0.85 + Expo SDK 56 defaults | Don’t override unless required. Set by react-native-gradle-plugin / expo-root-project after expo prebuild. |
To install the npm libraries provided by FlowX.AI you will need access to the private FlowX.AI Nexus registry. Consult your project DevOps.
react must satisfy React Native’s published peer dependency. For react-native@0.85.3 this is ^19.2.3; newer RN 0.85.x patches may shift it — check with npm view react-native@<your-version> peerDependencies. Installing React Native via the official template (Bare CLI) or Expo SDK 56 picks a compatible react automatically — don’t override it with a manual pin unless you have a reason.
Installation
Bare React Native CLI
Expo (SDK 56)
For new projects, bootstrap with the official React Native template so react and react-native ship as a matched pair that satisfies the peer dependency in the Warning above:npx @react-native-community/cli@latest init MyApp
cd MyApp
For existing projects, ensure react already satisfies your installed react-native’s declared peer (npm view react-native@<your-version> peerDependencies) before installing the FlowX SDK.Then install the FlowX SDK and peers:npm install \
@flowx/react-native-sdk@<version> \
@flowx/react-native-ui-toolkit@<version> \
@flowx/react-native-theme@<version> \
@flowx/core-sdk@<version> \
@flowx/core-theme@<version> \
@react-navigation/native \
@react-navigation/native-stack \
@react-navigation/elements \
react-native-screens \
react-native-safe-area-context \
react-native-svg \
react-native-enriched-markdown \
react-native-keyboard-controller \
react-native-reanimated \
react-native-worklets \
@react-native-community/datetimepicker \
@react-native-community/slider \
@react-native-segmented-control/segmented-control
Replace <version> with the correct version corresponding to your platform version.To find the right version, navigate to: Release Notes → Choose your platform version → Deployment guidelines → Component versions.
Then install iOS pods:cd ios && pod install && cd ..
Expo Go is not supported. react-native-keyboard-controller, react-native-reanimated@4, and react-native-worklets require a custom native build. Use expo-dev-client with EAS builds or expo prebuild.
This SDK release targets Expo SDK 56 (stable). Older Expo SDKs are not supported.| Expo SDK | Status | React Native | React | Notes |
|---|
| 56 | Recommended | 0.85.x | 19.2.3 (Expo SDK 56 pin; satisfies RN ^19.2.3) | Current target. New architecture is default. iOS 16.4 minimum. |
| 55 | Not supported | 0.83.x | 19.2.x | Use the previous @flowx/react-native-sdk tag. |
| ≤54 | Not supported | - | - | Missing required peers (worklets autolink, React 19 baseline). |
Align the project to Expo SDK 56:npx expo install expo --fix
--fix aligns react, react-native, react-native-reanimated, react-native-worklets, react-native-safe-area-context, react-native-screens, and other Expo-tracked peers to the versions validated for the installed Expo SDK. Re-run after every Expo bump.Install the FlowX SDK and peers with npx expo install (it picks Expo-validated versions and warns on incompatibilities; use it instead of npm install):npx expo install \
@flowx/react-native-sdk@<version> \
@flowx/react-native-ui-toolkit@<version> \
@flowx/react-native-theme@<version> \
@flowx/core-sdk@<version> \
@flowx/core-theme@<version> \
@react-navigation/native \
@react-navigation/native-stack \
@react-navigation/elements \
react-native-screens \
react-native-safe-area-context \
react-native-svg \
react-native-enriched-markdown \
react-native-keyboard-controller \
react-native-reanimated \
react-native-worklets \
@react-native-community/datetimepicker \
@react-native-community/slider \
@react-native-segmented-control/segmented-control \
expo-dev-client
Replace <version> with the correct version corresponding to your platform version.To find the right version, navigate to: Release Notes → Choose your platform version → Deployment guidelines → Component versions.
react, react-native, expo, and Expo built-ins are already in a fresh Expo project - don’t reinstall them. They are pinned by Expo SDK 56’s compatibility matrix; let npx expo install --fix resolve drift instead of pinning manually.Expo SDK 56 reference versions
These are the versions Expo SDK 56 validates. Use npx expo install <pkg> to install at the right pin; do not pin manually unless you must.| Package | Expo SDK 56 expected |
|---|
expo | ~56.0.3 |
expo-dev-client | ~56.0.14 |
expo-splash-screen | ~56.0.9 |
expo-status-bar | ~56.0.4 |
babel-preset-expo | ~56.0.6 |
@expo/cli | 56.1.2 |
react | 19.2.3 (Expo SDK 56 pin; satisfies react-native@0.85.3 peer ^19.2.3) |
react-native | 0.85.3 |
react-native-reanimated | 4.3.1 |
react-native-worklets | 0.8.3 |
react-native-safe-area-context | ~5.7.0 |
react-native-screens | 4.25.1 |
react-native-svg | 15.15.4 |
react-native-enriched-markdown | 0.5.0 |
react-native-keyboard-controller | 1.21.6 |
@react-native-community/datetimepicker | 9.1.0 |
@react-native-community/slider | 5.2.0 |
@react-native-segmented-control/segmented-control | 2.5.7 |
Generate native projects if your Expo project does not yet have ios/ and android/:npx expo prebuild --clean
Then install iOS pods:cd ios && pod install && cd ..
pod install is also run automatically by npx expo run:ios on first launch.app.json plugins
Most listed native modules autolink without an Expo config plugin. The ones that benefit from one:{
"expo": {
"plugins": [
"expo-dev-client",
["react-native-keyboard-controller", {}]
]
}
}
react-native-reanimated and react-native-worklets do not need a config plugin - the Babel plugin handles them. The @flowx/react-native-ui-toolkit plugin is covered in the Android Material 3 section below.Local build (no EAS)
For development on your own machine without EAS:npx expo run:ios # builds + runs on iOS simulator or device
npx expo run:android # builds + runs on Android emulator or device
First invocation runs expo prebuild if ios/ or android/ are absent, then builds via Xcode / Gradle. Requires local Xcode (iOS) and Android SDK / JDK (Android).Useful flags:npx expo run:ios --device # pick a connected physical device
npx expo run:ios --configuration Release # release build
npx expo run:android --variant release # release build
npx expo run:android --device <id> # pick device
After the first install, start Metro separately with the dev client:npx expo start --dev-client
The installed app on the simulator or device connects to Metro automatically.EAS Build
Add a development profile to eas.json with developmentClient: true so the artifact ships with the dev client:{
"build": {
"development": {
"developmentClient": true,
"distribution": "internal"
}
}
}
Then build:eas build --profile development --platform ios
eas build --profile development --platform android
Install the resulting artifact on device. Run npx expo start --dev-client to connect Metro.Metro config (monorepo)
The default Expo Metro config works in standard projects. For monorepos with symlinked workspaces, enable symlink resolution:// metro.config.js
const { getDefaultConfig } = require('expo/metro-config');
const config = getDefaultConfig(__dirname);
config.resolver.unstable_enableSymlinks = true;
module.exports = config;
Some peer dependencies require additional setup beyond npm install: Babel plugins, Expo config plugins, native project edits (Podfile, styles.xml, AndroidManifest.xml), or app-root providers. Check each library’s install guide and apply its setup steps. Examples: react-native-worklets needs a Babel plugin (see below), react-native-keyboard-controller needs an Expo config plugin in managed projects, and react-native-screens / react-native-safe-area-context rely on autolinking plus the providers shown later in this page.
Babel plugin
react-native-worklets/plugin must be the last plugin in your Babel config.
No manual config needed. babel-preset-expo (SDK 54+) auto-adds the worklets plugin when react-native-worklets is in node_modules.// babel.config.js
module.exports = function (api) {
api.cache(true);
return {
presets: ['babel-preset-expo'],
};
};
// babel.config.js
module.exports = {
presets: ['module:@react-native/babel-preset'],
plugins: [
'react-native-worklets/plugin',
],
};
Android Material 3 date picker (opt-in)
FlxDatePicker on Android renders the legacy AppCompat calendar by default. To use the Material 3 picker, the host app’s AppTheme must inherit from a Material 3 parent and the toolkit runtime flag material3 must be true. With the flag off, the legacy calendar renders and the theme change is irrelevant.
Register the @flowx/react-native-ui-toolkit config plugin. It rewrites AppTheme to a Material 3 parent and injects extra.flxUiToolkit.material3 = true into the app config, so no JS opt-in is needed:{
"expo": {
"plugins": [
"@flowx/react-native-ui-toolkit"
]
}
}
Then run npx expo prebuild --clean --platform android. Two steps.Step 1. Edit android/app/src/main/res/values/styles.xml:<!-- Before -->
<style name="AppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
<!-- ... -->
</style>
<!-- After -->
<style name="AppTheme" parent="Theme.Material3.DayNight.NoActionBar">
<!-- ... -->
</style>
Step 2. Opt in from JS. Pick one:Option A. FlxThemeProvider prop:import { FlxThemeProvider } from '@flowx/react-native-ui-toolkit'
export default function App() {
return (
<FlxThemeProvider material3>
{/* ... */}
</FlxThemeProvider>
)
}
Option B. Explicit call at app bootstrap (top of index.js):import { configureFlxUiToolkit } from '@flowx/react-native-ui-toolkit'
configureFlxUiToolkit({ material3: true })
No Gradle changes required. com.google.android.material:material is already on the classpath via androidx.appcompat. Skip both steps and FlxDatePicker keeps rendering the legacy calendar with no crash.
App-root providers
The renderer expects safe-area and keyboard providers above it in the tree:
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { KeyboardProvider } from 'react-native-keyboard-controller'
export default function App() {
return (
<SafeAreaProvider>
<KeyboardProvider>
{/* FlowX process view goes here */}
</KeyboardProvider>
</SafeAreaProvider>
)
}
The SDK mounts its own NavigationContainer internally, wrapped in NavigationIndependentTree. A host NavigationContainer is not required. If your app already uses @react-navigation/native, keep its NavigationContainer at the root. The SDK’s internal navigator stays isolated from it.
Authorization
The client app implements the authorization flow (using the OpenID Connect standard). The SDK expects a bearer token to be set via FlowX.setAccessToken(token) before starting a process.
import { FlowX } from '@flowx/react-native-sdk'
FlowX.setAccessToken(accessToken)
Call setAccessToken again whenever the token is refreshed.
Configuring the SDK
FlowX.configure(cfg) sets global SDK config. Call it once at app bootstrap, before starting any process.
import { FlowX } from '@flowx/react-native-sdk'
FlowX.configure({
baseURL: 'https://yourDomain.dev',
processApiPath: 'onboarding',
organizationId: '10000001-0001-0001-8001-100000000001',
language: 'en',
locale: 'en-US',
staticAssetsPath: 'https://yourDomain.dev/static',
isDraft: false,
})
FlxConfig parameters
| Name | Description | Type | Mandatory | Default |
|---|
baseURL | Base API URL | string | true | - |
processApiPath | Process subpath | string | true | - |
organizationId | FlowX-issued organization UUID. On self-hosted deployments it matches the ORGANIZATION_ID configured during the backend upgrade — see License and organization configuration. | string | true | - |
language | Language used to localize enumerations | string | false | - |
locale | Locale used to format dates, currency, numbers | string | false | - |
staticAssetsPath | Base path for static resources (icons, media). The SDK logs a warning if not set. | string | false | - |
themeId | Theme identifier (reserved, not consumed by the RN renderer yet) | string | false | - |
isDraft | Start the process in draft state | boolean | false | false |
Starting a process
FlowX.startProcess(opts) starts a new process instance and returns a FlxProcessHandle. The handle exposes a ProcessView component that you mount inside a screen.
import { FlowX, type FlxProcessHandle } from '@flowx/react-native-sdk'
import { useEffect, useState } from 'react'
export function OnboardingScreen() {
const [handle, setHandle] = useState<FlxProcessHandle | null>(null)
useEffect(() => {
let active = true
let pending: FlxProcessHandle | null = null
FlowX.startProcess({
workspaceId: '8f52744-8403-4e8d-...',
projectId: '111111-222222-333333-44444',
processName: 'client_identification',
params: { firstName: 'John', lastName: 'Smith' },
}).then((h) => {
if (!active) {
h.dispose()
return
}
pending = h
setHandle(h)
})
return () => {
active = false
pending?.dispose()
}
}, [])
if (!handle) return null
const { ProcessView } = handle
return <ProcessView />
}
StartProcessOptions
| Name | Description | Type | Mandatory | Example |
|---|
workspaceId | Workspace identifier | string | true | '8f52744-8403-4e8d-...' |
projectId | FlowX Project UUID. Get it from FlowX Dashboard → Projects → copy UUID from the project actions popover. | string | true | '111111-222222-...' |
appVersionId | Pin to a specific app version | string | false | - |
processName | Identifies the process to start | string | true | 'client_identification' |
params | Data passed when starting the process | Record<string, unknown> | false | { firstName: 'John' } |
resourceId | Resource identifier | string | false | - |
buildId | Pinned build identifier | string | false | - |
isModal | Render the process as a modal screen | boolean | false | false |
onClose | Called when the process view is closed | () => void | false | - |
onProcessStarted | Called when the main process instance is started. Receives the new processInstanceUuid. | (processInstanceUuid: string) => void | false | - |
Getting the process identifier
Open the FlowX Designer, navigate to the process, and copy the process name from the breadcrumbs. Use this value as processName.
Continuing a process
FlowX.continueProcess(opts) resumes an existing process instance by its UUID.
import { FlowX } from '@flowx/react-native-sdk'
const handle = await FlowX.continueProcess({
processInstanceUuid: 'a3f1c2d4-...',
})
ContinueProcessOptions
| Name | Description | Type | Mandatory |
|---|
processInstanceUuid | UUID of the process instance to resume | string | true |
isModal | Render the process as a modal screen | boolean | false |
onClose | Called when the process view is closed | () => void | false |
The process handle
Both startProcess and continueProcess resolve to a FlxProcessHandle:
interface FlxProcessHandle {
processInstanceUuid: string
ProcessView: ComponentType
dispose(): void
}
| Member | Description |
|---|
processInstanceUuid | UUID of the running process instance |
ProcessView | React component that renders the process screens. Mount it inside a screen in your navigation tree. |
dispose() | Tears down the running process and resets SDK stores. Call when the screen unmounts. |
Always call handle.dispose() when the host screen unmounts. Skipping it leaks SDK store state into the next process.
Full example
import { useEffect, useState } from 'react'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { KeyboardProvider } from 'react-native-keyboard-controller'
import { FlowX, type FlxProcessHandle } from '@flowx/react-native-sdk'
FlowX.configure({
baseURL: 'https://yourDomain.dev',
processApiPath: 'onboarding',
organizationId: '10000001-0001-0001-8001-100000000001',
language: 'en',
locale: 'en-US',
staticAssetsPath: 'https://yourDomain.dev/static',
})
function OnboardingScreen({ authToken }: { authToken: string }) {
const [handle, setHandle] = useState<FlxProcessHandle | null>(null)
useEffect(() => {
FlowX.setAccessToken(authToken)
let active = true
let pending: FlxProcessHandle | null = null
FlowX.startProcess({
workspaceId: '8f52744-8403-4e8d-...',
projectId: '111111-222222-333333-44444',
processName: 'client_identification',
params: { firstName: 'John' },
}).then((h) => {
if (!active) {
h.dispose()
return
}
pending = h
setHandle(h)
})
return () => {
active = false
pending?.dispose()
}
}, [authToken])
if (!handle) return null
const { ProcessView } = handle
return <ProcessView />
}
export default function App({ authToken }: { authToken: string }) {
return (
<SafeAreaProvider>
<KeyboardProvider>
<OnboardingScreen authToken={authToken} />
</KeyboardProvider>
</SafeAreaProvider>
)
}