# Project dependency
yarn add react-native-stallion

# Global or CI tooling
npm install -g @stallion/cli

npx pod-install

import com.stallion.StallionBridge

class MainReactHost : DefaultReactNativeHost(application) {
    override fun getJSBundleFile(): String? {
        return if (BuildConfig.DEBUG) {
            null // Metro handles resolution
        } else {
            StallionBridge.resolveBundlePath(applicationContext)
        }
    }
}

import ReactNativeStallion

func resolveBundleEndpoint() -> URL? {
    #if DEBUG
    return RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
    #else
    return StallionRouter.provideBundleURL()
    #endif
}

lopment traffic through the OTA SDK causes unnecessary network requests, breaks source maps, and interferes with debugging tooling. Release builds must delegate bundle resolution to the SDK to enable background downloads and atomic swaps.

3. Inject Runtime Credentials

The SDK requires a project identifier and an authentication token to communicate with the management console. These values must be embedded in native configuration files, not JavaScript constants, to prevent exposure in bundle artifacts.

iOS (Info.plist):

<key>StallionProjectId</key>
<string>prj_live_8f3a9c</string>
<key>StallionAppToken</key>
<string>tok_prod_x7k2m9</string>

Android (res/values/strings.xml):

<string name="StallionProjectId">prj_live_8f3a9c</string>
<string name="StallionAppToken">tok_prod_x7k2m9</string>

4. Wrap the Application Root and Handle Update Lifecycle

The SDK provides a higher-order component that initializes the update checker and exposes lifecycle hooks. A custom hook abstracts the update state for UI integration.

import { withBundleRouter, useUpdateState, triggerRestart } from 'react-native-stallion';

const AppContainer = () => {
  const { pendingUpdate, isRestartMandatory, releaseNotes } = useUpdateState();

  if (isRestartMandatory && pendingUpdate) {
    return (
      <View style={styles.overlay}>
        <Text>{releaseNotes || 'An update is ready.'}</Text>
        <Button title="Apply Now" onPress={triggerRestart} />
      </View>
    );
  }

  return <MainApplication />;
};

export default withBundleRouter(AppContainer);

Architecture Rationale: The root wrapper ensures the SDK initializes before any business logic executes. The useUpdateState hook decouples update metadata from UI rendering, allowing teams to implement silent background downloads, mandatory restart banners, or deferred update prompts based on product requirements. The triggerRestart function performs an atomic bundle swap, ensuring the new JavaScript context replaces the old one without partial state corruption.

5. Publish and Promote Artifacts

The deployment workflow follows a strict promotion model:

1. Generate the production bundle and upload it to a staging bucket via CLI.
2. Verify the artifact in the management console.
3. Promote the bundle to production with a defined rollout percentage.
4. Monitor crash rates and performance metrics.
5. Increment rollout or execute rollback if thresholds are breached.

stallion-cli publish \
  --platform ios \
  --bundle-path ./dist/main.jsbundle \
  --target-version 2.4.1 \
  --rollout 5

The --rollout flag defaults to 0, meaning only explicitly enrolled test devices receive the update. Incremental expansion (5% → 25% → 100%) aligns with standard canary deployment practices. The SDK automatically checks for updates on cold start and foreground transitions, applying patches in the background without interrupting user sessions.

Pitfall Guide

1. Attempting Native Module Swaps via OTA

Explanation: OTA only replaces the JavaScript bundle. Adding, removing, or updating native modules requires recompiling the native shell. Attempting to call a newly added native method from an OTA bundle will throw a runtime exception. Fix: Treat OTA as a JavaScript-only patching mechanism. Any change touching android/, ios/, or native dependencies must follow a standard app store release.

2. Bypassing Phased Rollouts

Explanation: Deploying to 100% of users immediately eliminates the safety net. If a bundle contains a silent logic error or performance regression, the entire user base is affected before telemetry can surface the issue. Fix: Always initialize releases at 1–5%. Use crash reporting (Sentry, Firebase Crashlytics) and APM tools to validate stability before expanding coverage.

3. Ignoring Health Check Markers

Explanation: The SDK relies on a health check signal to confirm a bundle is stable. If the application crashes before marking itself as healthy, the SDK assumes the bundle is defective and reverts on the next launch. Fix: Ensure your root component or initialization sequence calls the health confirmation method within the first 30 seconds of startup. Delayed health checks trigger false-positive rollbacks.

4. Shipping Unsigned Bundles in Production

Explanation: Unsigned artifacts are vulnerable to man-in-the-middle attacks and CDN compromise. An attacker could intercept the download request and inject malicious JavaScript. Fix: Enable bundle signing in the management console. Rotate signing keys quarterly. Verify signature validation is enabled in the SDK configuration before production deployment.

5. Overwriting Metro Dev Server in Release Builds

Explanation: Failing to branch on DEBUG/Release in native bundle resolution causes development builds to route through the OTA SDK. This breaks hot reloading, corrupts source maps, and generates unnecessary network traffic. Fix: Maintain explicit conditional logic in getJSBundleFile and bundleURL. Route development traffic to Metro and release traffic to the OTA SDK.

6. Treating OTA as a Feature Delivery Channel

Explanation: Using OTA to ship major features violates app store guidelines. Apple and Google permit OTA for bug fixes and minor adjustments, not for functional changes that alter the app's core purpose. Fix: Reserve OTA for patches, copy fixes, styling adjustments, and business logic tweaks. Major features must be bundled in native releases and submitted for review.

7. Neglecting Bundle Version Alignment

Explanation: Uploading a bundle targeting an app version that does not exist in the console, or mismatching semantic versions, causes the SDK to ignore the update or apply it to incompatible clients. Fix: Align bundle target versions with your native release cadence. Use CI/CD pipelines to automatically tag bundles with the correct --target-version flag based on package.json or app.json.

Production Bundle

Action Checklist

• Verify React Native version is 0.69 or higher before SDK integration
• Install react-native-stallion and link iOS native modules via npx pod-install
• Implement conditional bundle resolution in Android and iOS native hosts
• Inject project ID and app token into native configuration files
• Wrap the root component with the SDK's higher-order component
• Enable bundle signing and configure customer-managed keys if required
• Integrate CLI publish commands into CI/CD pipelines with automated version tagging
• Configure crash telemetry correlation with OTA rollout phases

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Bare React Native, small team	Managed OTA (Stallion)	Zero infrastructure overhead, phased rollouts, signed bundles	Low (managed SaaS)
Expo-managed project	Expo EAS Update	Native framework integration, unified tooling	Medium (Expo tier pricing)
Strict compliance, air-gapped environment	Self-hosted CodePush	Full control over infrastructure, no external dependencies	High (infra, security, on-call)
High-traffic app, frequent JS patches	Differential OTA + Phased Rollouts	Bandwidth efficiency, rapid recovery, granular risk control	Low (managed SaaS)
Native-heavy updates, infrequent JS changes	Standard App Store Releases	OTA provides minimal value, store review is acceptable	Low (no OTA cost)

Configuration Template

// stallion.config.ts
export const bundleRouterConfig = {
  projectId: process.env.STALLION_PROJECT_ID,
  appToken: process.env.STALLION_APP_TOKEN,
  healthCheckTimeout: 30000,
  autoRollbackOnCrash: true,
  signingVerification: 'strict',
  rolloutStrategy: {
    initialPercentage: 5,
    incrementStep: 25,
    maxRetries: 3,
    telemetryIntegration: 'sentry'
  }
};

# CI/CD Pipeline Snippet (GitHub Actions)
- name: Build JavaScript Bundle
  run: npx react-native bundle --entry-file index.js --platform ios --dev false --bundle-output ./dist/main.jsbundle

- name: Publish to OTA Console
  run: |
    stallion-cli publish \
      --platform ios \
      --bundle-path ./dist/main.jsbundle \
      --target-version ${{ github.ref_name }} \
      --rollout 5 \
      --release-notes "Patch: Fix navigation stack overflow"

Quick Start Guide

1. Install SDK & CLI: Run yarn add react-native-stallion and npm i -g @stallion/cli. Execute npx pod-install for iOS.
2. Wire Native Resolution: Override getJSBundleFile (Android) and bundleURL (iOS) to route release builds through the SDK while preserving Metro for development.
3. Inject Credentials: Add StallionProjectId and StallionAppToken to Info.plist and strings.xml. Generate tokens from the management console.
4. Wrap Root Component: Apply the SDK's higher-order component to your app root and implement a custom hook for update state management.
5. Publish First Patch: Build the production bundle, upload via CLI with --rollout 5, and verify the update downloads and applies on a test device. Monitor crash telemetry before expanding rollout.