Installation

Setting up SwiftPatch is straightforward. After this guide, you'll have the SDK and CLI installed, both platforms configured, and a verified connection to SwiftPatch.

Prerequisites

• React Native 0.76+
• Node.js 18+ and npm 9+
• CocoaPods for iOS (sudo gem install cocoapods)
• iOS 13.4+ / Android API 24+
• A SwiftPatch account with a project created

Already have a project?

Skip straight to Step 1: Install the SDK.

---

Step 1: Install the SDK

npm install @swiftpatch/react-native

---

Step 2: Install the CLI

npm install -g @swiftpatch/cli

Verify it works:

swiftpatch --version

Using npx?

You can prefix all CLI commands with npx @swiftpatch/cli instead of installing globally.

---

Step 3: Get Your App ID

1. Open the SwiftPatch Dashboard.
2. Go to your project Settings.
3. Copy the App ID.

Keep your App ID safe

Do not commit it directly in public repos. Use environment variables or build-time config instead.

---

Step 4: Add Native Credentials

iOS -- Info.plist

ios/YourApp/Info.plist

<key>SwiftPatchAppId</key>
<string>YOUR_APP_ID</string>

Android -- strings.xml

android/app/src/main/res/values/strings.xml

<string name="SwiftPatchAppId">YOUR_APP_ID</string>

---

Step 5: iOS Platform Setup

5a. Install CocoaPods

cd ios && pod install && cd ..

Pod install failing?

Try pod repo update first. On Apple Silicon, check your CocoaPods architecture setup.

5b. Update AppDelegate

Tell iOS to load the SwiftPatch bundle in release builds.

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
  }
}

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

Why the DEBUG check?

In development, React Native uses Metro for hot reloading. In release builds, SwiftPatch takes over bundle loading for OTA updates.

---

Step 6: Android Platform Setup

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()
      }
    }
}

React Native 0.82+?

See Android Setup for the updated integration.

---

Step 7: Wrap Your App

App.tsx

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

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

export default withSwiftPatch(App);

---

Step 8: Verify

Build and run your app:

npx react-native run-ios
# or
npx react-native run-android

Look for this log message:

[SwiftPatch] SDK initialized successfully

Not seeing the log?

Check that:

• Your App ID matches the dashboard.
• You ran pod install (iOS).
• You wrapped your root component with withSwiftPatch.
• You're checking the right log output (Metro terminal or adb logcat).

Verify CLI authentication:

swiftpatch whoami
# If not logged in:
swiftpatch login

You're all set! Your app is ready to receive OTA updates.

---

Troubleshooting

Problem	Solution
Module not found: @swiftpatch/react-native	Run npm install and restart Metro with --reset-cache.
pod install fails	Delete ios/Pods and ios/Podfile.lock, then run pod install again.
SDK log missing	Ensure withSwiftPatch wraps your root component.
Android build fails	Run cd android && ./gradlew clean && cd .. and rebuild.
CLI returns unauthorized	Run swiftpatch login.

---

Next Steps

• Configuration -- Customize update strategies and rollback policies
• Your First Update -- Deploy your first OTA update