flowboard-react

flowboard-react

Flowboard React Native SDK for SDUI onboarding flows.

It supports:

• Expo development builds and prebuild/EAS workflows
• React Native CLI apps
• JSON-driven onboarding with custom screens and full Flowboard renderer support

Quick Start

Install the SDK:

npm install flowboard-react

Install the native peer dependencies in one step:

npx --package flowboard-react flowboard-setup

Preview the commands first:

npx --package flowboard-react flowboard-setup --dry-run

flowboard-react keeps heavy native modules as peer dependencies to avoid duplicate binaries and version conflicts in host apps. The setup command installs the required peer set for you.

By default, flowboard-setup installs only missing peers. If your app already declares one of these native packages, the setup command leaves it untouched so it does not force a downgrade. Use --upgrade to install Flowboard's validated package matrix explicitly.

Expo Support

Expo Go is not supported. This SDK depends on custom native modules, so Expo users need a development build, expo prebuild, or EAS Build.

After running flowboard-setup, add the plugin to your app config:

{
  "expo": {
    "plugins": ["flowboard-react"]
  }
}

If your onboarding flow uses request_permission actions, configure the plugin with permission options:

{
  "expo": {
    "plugins": [
      [
        "flowboard-react",
        {
          "permissions": ["camera", "photos", "microphone"],
          "permissionMessages": {
            "camera": "Allow $(PRODUCT_NAME) to access the camera during onboarding.",
            "photos": "Allow $(PRODUCT_NAME) to access your photo library during onboarding.",
            "microphone": "Allow $(PRODUCT_NAME) to access the microphone during onboarding."
          }
        }
      ]
    ]
  }
}

Supported plugin options:

• permissions: notifications, contacts, location, camera, microphone, photos
• permissionMessages: override default iOS usage descriptions for supported Flowboard permissions
• iosPermissions: append advanced react-native-permissions iOS entries directly
• androidPermissions: append raw Android permissions directly
• includeVectorIconFonts: defaults to false
• iconFonts: override the bundled FontAwesome6 font file list

The plugin does three things:

• Composes react-native-permissions for iOS permission Podfile setup when needed
• Adds Android manifest permissions for Flowboard permission actions
• Optionally bundles FontAwesome 6 fonts through expo-font when includeVectorIconFonts is enabled

If your Expo app needs Flowboard's bundled icon fonts, enable them explicitly:

{
  "expo": {
    "plugins": [
      [
        "flowboard-react",
        {
          "includeVectorIconFonts": true
        }
      ]
    ]
  }
}

React Native CLI Support

flowboard-setup installs the validated peer set for React Native CLI apps too, but some native configuration still belongs to the host app.

After installation:

• Run cd ios && pod install.
• Configure react-native-permissions in your Podfile, Info.plist, and AndroidManifest.xml if your flow uses permission actions.
• Configure react-native-vector-icons font bundling if your host app does not already do it.

The SDK does not edit your app config files automatically in this phase. It installs the packages and prints the exact next steps.

What flowboard-setup Installs

Package	Why it stays a peer
@react-native-async-storage/async-storage	Native persistence backend
@react-native-masked-view/masked-view	Native masked rendering
lottie-react-native	Native animation runtime
react-native-device-info	Native device/app metadata
react-native-get-random-values	Native crypto randomness bridge
react-native-in-app-review	Native review prompt support
react-native-linear-gradient	Native gradient rendering
react-native-pager-view	Native paged screen containers
react-native-permissions	Native permissions bridge
react-native-safe-area-context	Native safe-area insets
react-native-svg	Native vector rendering
react-native-vector-icons	Native font/icon bundling

Expo apps also get expo-font so the plugin can bundle the FontAwesome 6 fonts used by Flowboard icons when includeVectorIconFonts is enabled.

These JS-only helpers are bundled by the SDK itself and do not need to be installed by host apps:

• react-native-mask-input
• expr-eval
• uuid

Installation Flags

The setup command supports:

• --dry-run: print commands without installing anything
• --yes: skip the confirmation prompt
• --upgrade: force reinstall of the validated package set
• --verbose: print each command before it runs
• --project-root <path>: target a different host app directory

Usage

Initialize Flowboard once near app startup:

import React from 'react';
import { Flowboard, FlowboardProvider } from 'flowboard-react';

export default function App() {
  React.useEffect(() => {
    Flowboard.init({
      apiToken: 'YOUR_BEARER_TOKEN',
      debug: true,
    });
  }, []);

  return <FlowboardProvider>{/* your app */}</FlowboardProvider>;
}

Launch the default onboarding:

await Flowboard.launchOnboarding({
  customScreenBuilder: (ctx) => {
    if (ctx.screenData.id === 'paywall') {
      return (
        <MyPaywall
          onClose={ctx.onNext}
          onSignup={() => ctx.onJumpTo('signup')}
        />
      );
    }
    return null;
  },
  onOnboardEnd: (formData) => {
    console.log('Flow completed:', formData);
  },
});

Launch a specific onboarding by ID:

await Flowboard.launchOnboardingById('YOUR_ONBOARDING_ID', {
  locale: 'fr_FR',
  version: 'draft',
  onOnboardEnd: (formData) => {
    console.log('Specific flow completed:', formData);
  },
});

Re-initialize if you rotate credentials or environment:

await Flowboard.reinit();

API

• Flowboard.init({ apiToken, debug, enableAnalytics })
• Flowboard.launchOnboarding({ customScreenBuilder, customActionBuilder, onOnboardEnd, onStepChange, enableAnalytics, alwaysRestart, resumeProgress })
• Flowboard.launchOnboardingById(onboardingId, { locale, version, customScreenBuilder, customActionBuilder, onOnboardEnd, onStepChange, enableAnalytics, alwaysRestart, resumeProgress })
• Flowboard.reinit()
• FlowboardProvider

Jump To Actions

Use jump_to in Flowboard JSON:

{
  "type": "button",
  "action": "jump_to",
  "actionData": {
    "screenId": "signup"
  },
  "properties": {
    "label": "Jump to Sign Up"
  }
}

Inside custom screens, use ctx.onJumpTo(screenId):

customScreenBuilder: (ctx) => {
  if (ctx.screenData.id === 'paywall') {
    return (
      <Button title="Jump to Sign Up" onPress={() => ctx.onJumpTo('signup')} />
    );
  }
  return null;
};

Runtime Resilience

Flowboard wraps its native peers behind defensive adapters.

If a native module is installed but not linked or configured correctly:

• the SDK logs a development warning once
• storage falls back to memory
• permissions return unavailable
• in-app review is skipped
• gradients, masks, paging, SVG, and Lottie fall back to simplified rendering where possible

This does not replace installation. Metro still requires the peer packages to exist in the host app dependency graph.

Troubleshooting

Plugin "flowboard-react" was not found

• Make sure flowboard-react is installed in the host app.
• Re-run npx --package flowboard-react flowboard-setup.

Icons render as empty boxes

• Expo: confirm plugins: ["flowboard-react"] is present and rebuild the development client.
• React Native CLI: confirm react-native-vector-icons fonts are bundled in the native app.

Permission requests do nothing on iOS

• Make sure react-native-permissions is configured in the host app Podfile.
• Confirm the matching Info.plist usage descriptions exist.
• Re-run pod install.

Warnings about unavailable native modules

• The package is present, but native setup is incomplete.
• Rebuild the app after installing peers.
• Verify pod install, Android permissions, and Expo plugin setup for the affected module.

Development

yarn typecheck
yarn test
yarn lint

Notes

• Custom fonts must be available in the host app when using fontFamily.
• Google Fonts on iOS/Android can be loaded at runtime:
  • Expo: install expo-font and @expo-google-fonts/<family> in your app, then use fontFamily + numeric fontWeight in JSON.
  • Bare React Native (non-Expo): install @expo-google-fonts/<family> and react-native-dynamic-fonts; Flowboard will load those assets at runtime automatically.
  • Advanced/custom source: register a provider with registerGoogleFontProvider and return either true (uses requested native name) or the actual loaded native font name string.
• Asset images/Lottie ("source": "asset") should be provided as uri or through a custom loader in the host app.
• Radar charts support optional autoFitLabels (default true) and labelOffset (default max(20, fontSize * 1.5)) to keep axis labels inside bounds.

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT