Skip to main content

Quick Start

Go from zero to a live OTA update in five steps. You'll create an account, install the SDK, configure your app, and deploy an update -- no app store review needed.

Prerequisites
  • React Native 0.76+ with a working project
  • Node.js 18+ and npm 9+
  • CocoaPods installed (iOS only)
  • A release build running on a device or simulator
New to React Native?

Follow the React Native environment setup first, then come back.

Step 1: Sign Up and Create Your App​

Go to app.swiftpatch.io and create a free account.

  1. Click + New App.
  2. Enter your app name.
  3. Select your platform -- iOS, Android, or both.
  4. Click Create.
  5. Open Settings and copy your App ID.
tip

Your App ID looks like app_xxxxxxxxxxxxxxxx. You'll need it in the next step.

Step 2: Install the SDK​

npm install @swiftpatch/react-native

iOS -- install CocoaPods dependencies:

cd ios && pod install && cd ..

Android -- no extra setup needed. The SDK auto-links.

Step 3: Configure Your App​

You'll edit three things: native config files, native entry points, and your JavaScript entry point.

3a. Add Your App ID​

iOS -- ios/YourApp/Info.plist:

ios/YourApp/Info.plist
<key>SwiftPatchAppId</key>
<string>YOUR_APP_ID</string>

Android -- android/app/src/main/res/values/strings.xml:

android/app/src/main/res/values/strings.xml
<string name="SwiftPatchAppId">YOUR_APP_ID</string>

3b. Point Native Code to SwiftPatch​

SwiftPatch needs to control which JavaScript bundle your app loads so it can apply OTA updates.

iOS (Swift -- React Native 0.76+):

ios/YourApp/AppDelegate.swift
import react_native_swiftpatch

@main
class AppDelegate: RCTAppDelegate {
  override func bundleURL() -> URL? {
    #if DEBUG
    return RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
    #else
    return SwiftPatchModule.getBundleURL()
    #endif
  }
}

iOS (Objective-C):

ios/YourApp/AppDelegate.mm
#import "SwiftPatchModule.h"

@implementation AppDelegate

- (NSURL *)bundleURL {
#if DEBUG
  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
#else
  return [SwiftPatchModule getBundleURL];
#endif
}

@end

Android:

android/app/src/main/java/.../MainApplication.kt
import com.swiftpatch.SwiftPatchModule

class MainApplication : Application(), ReactApplication {
  override val reactNativeHost: ReactNativeHost =
    object : DefaultReactNativeHost(this) {
      override fun getJSBundleFile(): String? {
        return SwiftPatchModule.getJSBundleFile(applicationContext)
          ?: super.getJSBundleFile()
      }
    }
}

3c. Wrap Your App​

App.tsx
import { withSwiftPatch } from '@swiftpatch/react-native';

function App() {
  return <YourApp />;
}

export default withSwiftPatch(App);

Verify the SDK​

Run your app in release mode:

npx react-native run-ios --mode Release

Look for this in the logs:

[SwiftPatch] SDK initialized successfully
Debug mode skips updates

The SDK only fetches OTA updates in release builds. In debug mode, your app uses Metro as usual.

Step 4: Deploy Your First Update​

Make a visible change, then push it over the air.

4a. Edit Some Text​

src/screens/HomeScreen.tsx
function HomeScreen() {
  return (
    <View>
      <Text>Hello from SwiftPatch! OTA is working.</Text>
    </View>
  );
}

4b. Install the CLI and Deploy​

npm install -g @swiftpatch/cli
swiftpatch login
swiftpatch deploy -p ios --hermes -n "My first OTA update"
Always pass --hermes if your app uses Hermes

React Native 0.70+ enables Hermes by default. Deploying without --hermes causes a crash loop.

Step 5: Verify the Update​

  1. Kill the app completely.
  2. Reopen it -- the SDK downloads the update.
  3. Kill and reopen once more. You should see your updated text.
Two restarts?

By default, SwiftPatch applies updates on the next launch after download. The first open downloads; the second loads the new code. You can change this in the SDK configuration.

Troubleshooting​

SymptomSolution
No SDK initialized logCheck that SwiftPatchAppId is set in Info.plist / strings.xml and matches your dashboard App ID.
Update does not appearMake sure you're running a release build. Debug builds skip OTA updates.
App crashes after updateDeploy with --hermes. The SDK auto-rolls back after two crashes within 10 seconds.
Version mismatchThe SDK matches on your native binary version exactly. Check MARKETING_VERSION (iOS) or versionName (Android).

Next Steps​