react-native-ota-hot-update

react-native-ota-hot-update

This React Native module allows you to manage hot updates (in-app update) with minimal configuration, similar to Code Push. You can control versioning and host the JS bundle yourself. The library handles the installation of updates after the bundle is downloaded from your server or Git repository. With Code Push retiring soon, this library gives you full control over your update process, whether hosting the bundle on your own server or in a Git repository.

Key features:

• Host the bundle on your own server or in a Git repository.
• Rollback function
• Crash Handling: Handles crash exceptions when an incorrect bundle is updated and will automatically roll back to the previous bundle version.
• bundle management features

• Demo via server

iOS GIF	Android GIF

• Demo via git repository

iOS GIF	Android GIF

• Demo bundle management

New architecture supported

New architecture backward compatibility supported from version 2, it also supported old architecture, for source code of version 1.x.x please refer to branch oldArch, you might need install version 1.x.x if you are using react native < 0.70

🚀 Preview Release: Enhanced Bundle Management (v2.4.0-rc.1)

We're excited to introduce a preview release with enhanced bundle management features! Version 2.4.0-rc.1 includes:

• Configurable bundle history: Manage multiple bundle versions (configurable via maxBundleVersions)
• New APIs: getBundleList(), deleteBundleById(), clearAllBundles()
• Bundle identification: Descriptive folder names with version and timestamp
• Automatic cleanup: Older bundles are automatically removed when exceeding the limit

This is an experimental release for testing. Please try it out and share your feedback! All discussions and issues related to this feature can be found in PR #132.

• Branch: task/manage_bundle

To install the preview version:

yarn add react-native-ota-hot-update@2.4.0-rc.1

Installation

if you don't want to manage the download progress, need to install blob util together:

yarn add react-native-ota-hot-update && yarn add react-native-blob-util

Auto linking already, need pod install for ios:

cd ios && pod install

Expo

Modify app.json:

"plugins": [
      "react-native-ota-hot-update",
      ...
    ]

IOS

Open AppDelegate.m and add this:

#import "OtaHotUpdate.h"
...
{
#if DEBUG
  return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
#else
  return [OtaHotUpdate getBundle]; ## add this line
#endif
}

IOS React native 0.77 or above

From react native 0.77, AppDelegate changed to swift file, so the configuration will be change a bit.

Open AppDelegate.swift:

import react_native_ota_hot_update
...

override func bundleURL() -> URL? {
        #if DEBUG
            RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
        #else
            OtaHotUpdate.getBundle()  // -> Add this line
        #endif
}

For downloading in background mode on IOS, following this (optional):

AppDelegate.h:

@property (nonatomic, assign) UIBackgroundTaskIdentifier taskIdentifier;

AppDelegate.mm:

- (void)applicationWillResignActive:(UIApplication *)application {
   if (self.taskIdentifier != UIBackgroundTaskInvalid) {
      [application endBackgroundTask:self.taskIdentifier];
      self.taskIdentifier = UIBackgroundTaskInvalid;
   }

   __weak AppDelegate *weakSelf = self;
   self.taskIdentifier = [application beginBackgroundTaskWithName:nil expirationHandler:^{
      if (weakSelf) {
          [application endBackgroundTask:weakSelf.taskIdentifier];
          weakSelf.taskIdentifier = UIBackgroundTaskInvalid;
      }
   }];
}

AppDelegate.swift(RN >= 0.77):

class AppDelegate: RCTAppDelegate {
var taskIdentifier: UIBackgroundTaskIdentifier = .invalid
...

  public override func applicationDidEnterBackground(_ application: UIApplication) {
    if taskIdentifier != .invalid {
      application.endBackgroundTask(taskIdentifier)
      taskIdentifier = .invalid
    }

    taskIdentifier = application.beginBackgroundTask(withName: "OTAUpdate") { [weak self] in
      if let strongSelf = self {
        application.endBackgroundTask(strongSelf.taskIdentifier)
        strongSelf.taskIdentifier = .invalid
      }
    }
  }

  public override func applicationWillEnterForeground(_ application: UIApplication) {
    if taskIdentifier != .invalid {
      application.endBackgroundTask(taskIdentifier)
      taskIdentifier = .invalid
    }
  }

Android

Open MainApplication.kt and add these codes bellow:

import com.otahotupdate.OtaHotUpdate
...
override val reactNativeHost: ReactNativeHost =
  object : DefaultReactNativeHost(this) {
    ...
    override fun getJSBundleFile(): String? {
      return OtaHotUpdate.bundleJS(this@MainApplication)
    }
    ...
  }

MainApplication.java:

		@Nullable
		@Override
		protected String getJSBundleFile() {
			return OtaHotUpdate.getBundleJS(this);
		}

Android in react native 0.82 or above:

  override val reactHost: ReactHost by lazy {
    getDefaultReactHost(
      context = applicationContext,
      packageList =
        PackageList(this).packages.apply {
          // Packages that cannot be autolinked yet can be added manually here, for example:
          // add(MyReactNativePackage())
        },
      jsBundleFilePath = OtaHotUpdate.bundleJS(applicationContext)
    )
  }

For java it maybe can be like: OtaHotUpdate.Companion.getBundleJS(this) depend on kotlin / jdk version on your project, you can use android studio to get the correct format coding.

If want to remove bundle wrong handler, pass false param in getBundleJS like this:

return OtaHotUpdate.bundleJS(this@MainApplication, false)

Open AndroidManifest.xml :

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

<application ... android:requestLegacyExternalStorage="true"

That's it, can check the example code

Remember hot update just work at release mode, debug mode won't working

Control Hot Update via Server

With this method, you can host the bundle JS on your own server. The app fetches the updates directly from the server, allowing for dynamic updates.

For detailed instructions on how to implement this, refer to DOC_OTA_SERVER.md.

Control Hot Update via Git Repository

This method allows you to use a Git repository to host the bundle JS. The app pulls updates directly from the repository, providing an easy and version-controlled way to manage updates.

For detailed instructions on how to implement this, refer to DOC_OTA_GIT.md.

Build a Custom Admin Panel with CMS

Using Strapi, you can build a tailored admin panel to manage React Native hot updates effectively. This approach allows you to centralize the control of versioning and OTA updates while providing a user-friendly interface for managing content. To get started, refer to the detailed steps and code examples in this guide. For additional details, see OTA_CMS.md.

License

MIT

Sponsor this project

https://paypal.me/vantuan88291

Architecture / Sequence Diagram

Paste the content below into https://sequencediagram.org/ to render the flow diagram.

title react-native-ota-hot-update - Main Flow

actor Developer
participant "Your Server\n(or Git Repo)" as Server
participant "RN App" as App
participant "Native Module\n(iOS / Android)" as Native
participant "Local Storage\n& File System" as Local

== Download & Install Update ==

Developer->Server: Upload bundle.zip + update.json
App->Server: Fetch update.json → check new version available
App->Server: Download bundle.zip
Server-->App: bundle.zip saved to local path
App->Native: setupBundlePath(zipPath, version)
Native->Local: Unzip → output_v{version}_{timestamp}/bundle
Native->Local: Save bundle PATH to SharedPrefs / UserDefaults
Native-->App: success

alt restartAfterInstall = true
    App->Native: restart()
end

== App Startup - Which Bundle to Load? ==

App->Native: getBundle() / bundleJS()
Native->Local: Read saved PATH
alt PATH exists AND file on disk AND app version matches
    Native-->App: Use OTA bundle path
else
    Native-->App: Use default bundle (built-in)
end
App->App: Load JS Bundle

== Crash Auto-Rollback ==

App->App: Crash within 2s of startup
Native->Local: Restore previous bundle PATH
Native->App: Restart app with safe bundle