Skip to content

Using Storyteller SDK with Expo#

This guide will help you set up the Storyteller SDK in your Expo project. The configuration depends on which version of the Storyteller SDK you're using.

Storyteller includes native code, so use a development build or a production build that includes the SDK. It is not available in Expo Go. See Expo's custom native code guidance.

Choose Your Version#

For Storyteller SDK v11.0.0+#

  • Requires: React Native New Architecture enabled
  • Expo SDK: 53+ recommended

For React Native SDK 12, also follow the Android host requirements in the v12 migration guide. The Storyteller config plugin configures iOS CocoaPods sources and the core native SDK version; it does not set Android Kotlin/Compose versions or enable the New Architecture for you.

For Storyteller SDK v10.x#

  • Requires: React Native New Architecture disabled
  • Expo SDK: use a version that still supports the Legacy Architecture. Expo SDK 55 and later cannot disable the New Architecture; see Expo's architecture guidance. The v10 examples below describe the historical 10.8.2 package.

Installation#

Install the SDK using npm or yarn:

# For latest version (v11.0.0+)
npm install @getstoryteller/react-native-storyteller-sdk

# For v10.x
npm install @getstoryteller/react-native-storyteller-sdk@^10.8.2 # or your desired version

or

# For latest version (v11.0.0+)
yarn add @getstoryteller/react-native-storyteller-sdk

# For v10.x
yarn add @getstoryteller/react-native-storyteller-sdk@^10.8.2 # or your desired version

Configure Expo Plugin#

Add the Storyteller plugin to your app.json or app.config.js:

{
  "expo": {
    "name": "your-app-name",
    "plugins": ["@getstoryteller/react-native-storyteller-sdk"]
  }
}

Architecture Configuration#

For SDK v11.0.0+ (New Architecture Required)#

Expo SDK 53 and 54 enable the New Architecture by default. SDK 52 enables it for newly created projects, but existing upgraded projects may need to opt in. For SDK 52–54, use the following app configuration when you need to enable it explicitly. SDK 55 and later always use the New Architecture and no longer need the newArchEnabled setting. See Expo's architecture guidance.

{
  "expo": {
    "plugins": ["@getstoryteller/react-native-storyteller-sdk"],
    "newArchEnabled": true,
    "ios": {
      "newArchEnabled": true
    },
    "android": {
      "newArchEnabled": true
    }
  }
}

For SDK v10.x (New Architecture Must Be Disabled)#

On an Expo version that supports the Legacy Architecture, explicitly disable the New Architecture for Storyteller v10.x. The following configuration applies through Expo SDK 54; it cannot make v10.x work on SDK 55 or later:

{
  "expo": {
    "plugins": ["@getstoryteller/react-native-storyteller-sdk"],
    "newArchEnabled": false,
    "ios": {
      "newArchEnabled": false
    },
    "android": {
      "newArchEnabled": false
    }
  }
}

Build Your Development Client#

After configuration, rebuild your development client:

# Clean prebuild (recommended when changing architecture settings)
npx expo prebuild --clean

npx expo run:ios
npx expo run:android

Upgrading from 11.0.5 or earlier on Expo apps#

Skip this section if you're installing the SDK for the first time.

If you previously prebuilt your project with Storyteller SDK version 11.0.5 or earlier, the config plugin may have added an Android autolinking exclusion to your project. This exclusion can prevent the TurboModule from registering correctly on newer Expo versions (Expo 52, 53, and 54).

Steps:

  1. Open android/settings.gradle in your Expo app and remove any line excluding this package from Expo autolinking, for example:
expoAutolinking.exclude = (expoAutolinking.exclude ?: []) + ['@getstoryteller/react-native-storyteller-sdk']
  1. Regenerate native projects so the change persists:
npx expo prebuild --clean
  1. Rebuild and run:
npx expo run:android
npx expo run:ios

Troubleshooting#

Gradle codegen dependency error on Android (Expo SDK 52)#

Symptom (example error):

A problem was found with the configuration of task ':getstoryteller-react-native-storyteller-sdk:generateCodegenArtifactsFromSchema'.
Gradle detected a problem with the following location: node_modules/@getstoryteller/react-native-storyteller-sdk/android/build/generated/source/codegen/schema.json.
Reason: Task ':getstoryteller-react-native-storyteller-sdk:generateCodegenArtifactsFromSchema' uses this output of task ':getstoryteller_react-native-storyteller-sdk:generateCodegenSchemaFromJavaScript' without declaring a dependency.

This indicates a mismatch in the React Native codegen task wiring, typically caused by version misalignment between Expo SDK, react-native, and the react-native-gradle-plugin when using New Architecture (required for v11+).

Recommended fix:

  • Update to Expo SDK 53 or later. This aligns the toolchain and resolves the codegen task ordering issue reported on Expo 52.

If you must stay on Expo SDK 52 you can manually set the generateCodegenArtifactsFromSchema task to depend on the generateCodegenSchemaFromJavaScript task. This is not recommended as it will not be automatically updated when the schema changes.

When contacting support, please share:

  • expo version (Expo SDK)
  • react-native version
  • react-native-gradle-plugin version (from android/settings.gradle)
  • Your android/settings.gradle contents

Note: A client reported this error on Expo 52 with react-native 0.77.3 and resolved it by upgrading to Expo 53.

TurboModuleRegistry error on startup (Expo 54)#

Symptom:

Expo 54 error: Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'StorytellerSdk' could not be found.

Checklist:

  • Use Storyteller SDK 11.0.6 or later for the corrected Android autolinking behavior. Keep the SDK version selected for your integration; do not downgrade a current v12 installation to 11.0.6.
  • Ensure there is no expoAutolinking.exclude line referencing @getstoryteller/react-native-storyteller-sdk in android/settings.gradle.
  • Ensure the Storyteller plugin is present in app.json/app.config as shown above.
  • Clean and regenerate native projects:
npx expo prebuild --clean
npx expo run:android
  • If the issue persists, clear Gradle caches (delete android/.gradle and android/build) and rebuild.

Implementation Examples#

import StorytellerSdk from '@getstoryteller/react-native-storyteller-sdk';

const initializeStoryteller = async () => {
  try {
    await StorytellerSdk.initialize('YOUR_API_KEY', 'USER_ID');
    console.log('Storyteller initialized successfully');
  } catch (error) {
    console.error('Storyteller initialization error:', error);
  }
};

// ...rest of your code

import StorytellerSdk from '@getstoryteller/react-native-storyteller-sdk';

const initializeStoryteller = () => {
  StorytellerSdk.initialize(
    {
      apiKey: 'YOUR_API_KEY',
      externalId: 'USER_ID',
    },
    (callback: { result: boolean, message: string }) => {
      console.log(`Result: ${callback.result}, Message: ${callback.message}`);

      if (callback.result) {
        console.log('Storyteller initialized successfully');
      } else {
        console.error('Failed to initialize:', callback.message);
      }
    }
  );

// ...rest of your code
}

Expo Showcase App#

We provide an Expo Showcase app that demonstrates how to integrate and use the Storyteller SDK with Expo. Visit the Showcase App page for more information.

Next Steps#

Support#