Expo integration with React Native Stallion

Integrate Expo + EAS Build with React Native Stallion OTA updates using expo-stallion-plugin. Learn how to configure the Expo plugin, export embedded bundles for iOS/Android, and publish them to Stallion.

Minimum SDK version:

Full Expo support requires minimum React Native Stallion SDK version 2.3.0.

Expo Integration with React Native Stallion

This guide shows the recommended Expo workflow with Stallion:

  • Use the Expo config plugin expo-stallion-plugin to configure native iOS/Android to load the JavaScript bundle from Stallion.
  • Generate embedded bundles with npx expo export:embed for each platform.
  • Publish those bundles to Stallion using npx stallion publish-bundle with --custom-bundle-path.

Requirements

  • An Expo app that can run npx expo prebuild (or is already prebuilt)
  • react-native-stallion installed in your app
  • Access to Stallion credentials:
    • projectId
    • appToken (should start with spb_)
  • (Recommended) Bundle signing private key. See Bundle Signing.

Step 1: Install dependencies

Install the config plugin and the Stallion SDK:

npm install expo-stallion-plugin react-native-stallion

Step 2: Configure the Expo plugin

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

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-stallion-plugin",
        {
          "projectId": "your-project-id",
          "appToken": "spb_your-app-token",
          "publicSigningKey": "YOUR_PUBLIC_KEY_HERE"
        }
      ]
    ]
  }
}

If you use Bundle Signing, set publicSigningKey to the base64-encoded contents of public-key.pem (the long string between the BEGIN/END lines).

app.config.js

export default {
  expo: {
    plugins: [
      [
        "expo-stallion-plugin",
        {
          projectId: "your-project-id",
          appToken: "spb_your-app-token",
          // Optional: required only if you use Stallion Bundle Signing
          publicSigningKey: "YOUR_PUBLIC_KEY_HERE",
        },
      ],
    ],
  },
};

Migrating from Expo Updates / EAS Updates:

If you previously used Expo Updates, you can keep the package installed, but ensure your app is configured to use Stallion for bundle loading in production (handled by the plugin). Remove any Expo Updates settings that could confuse rollout/debugging.

Step 3: Prebuild and build your app

Run prebuild so the plugin can patch native iOS and Android projects:

npx expo prebuild

Then create a development/production build as you normally do (for example with EAS Build):

eas build --platform ios
eas build --platform android

Step 4: Create embedded bundles (iOS + Android)

Stallion publishes the bundle outputs you generate. Create the embedded bundle artifacts using expo export:embed.

iOS bundle

npx expo export:embed \
  --platform ios \
  --dev false \
  --reset-cache \
  --bundle-output ./build-ios/main.jsbundle \
  --assets-dest ./build-ios \
  --bytecode

Android bundle

npx expo export:embed \
  --platform android \
  --dev false \
  --reset-cache \
  --bundle-output ./build-android/index.android.bundle \
  --assets-dest ./build-android \
  --bytecode

About --bytecode:

Use --bytecode when your app uses Hermes bytecode. If you’re not using Hermes, omit that flag.

Step 5: Publish the bundle to Stallion

Use stallion publish-bundle and point --custom-bundle-path to the folder that contains the exported bundle + assets.

Minimum stallion-cli version:

The --custom-bundle-path flag requires minimum stallion-cli v2.4.3.

Example (iOS)

npx stallion publish-bundle \
  --upload-path=stallion-test/expo/main \
  --platform=ios \
  --release-note="Release 1.0.0" \
  --custom-bundle-path=build-ios \
  --private-key=./stallion/secrets/private-key.pem

Example (Android)

npx stallion publish-bundle \
  --upload-path=stallion-test/expo/main \
  --platform=android \
  --release-note="Release 1.0.0" \
  --custom-bundle-path=build-android \
  --private-key=./stallion/secrets/private-key.pem

Troubleshooting

expo export:embed fails or is missing

  • Use npx expo ... (recommended) instead of relying on a global Expo install.
  • Ensure your app is on a recent Expo SDK that supports export:embed.

Publish succeeds but app does not pick up updates

  • Confirm you built the app with expo-stallion-plugin enabled (the plugin runs during prebuild / EAS build).
  • Confirm you published to the correct --upload-path bucket and correct --platform.
  • Confirm --custom-bundle-path points to the folder containing the generated bundle file:
    • iOS expects main.jsbundle in build-ios/
    • Android expects index.android.bundle in build-android/