react-native-github-ota

GitHub-based OTA (Over-The-Air) updates for React Native / Expo apps.

Downloads JS bundles from a GitHub Release (ota-latest tag) and applies them on next app restart — no app-store review needed.

How It Works

1. A GitHub Action builds your JS bundle on every push to main and uploads it to a GitHub Release tagged ota-latest.
2. This library compares the current build commit with the remote branch using the GitHub API.
3. When an update is available, it downloads the bundle to the device and prompts the user to restart.
4. On next launch, your native bootstrap code loads the downloaded bundle instead of the built-in one.

Installation

npm install react-native-github-ota
# or
yarn add react-native-github-ota

Peer Dependencies

Make sure these are installed in your project:

• expo-file-system (>= 16)
• react (>= 18)
• react-native (>= 0.72)

Quick Start

Run the init command to set everything up automatically:

npx github-ota-init

This will:

1. Copy the GitHub Actions workflow into .github/workflows/ota-bundle.yml
2. Add embed-commit and prebuild scripts to your package.json
3. Add the config plugin to your app.json — native code is applied automatically on expo prebuild
4. For bare RN projects (no Expo): patches MainApplication.kt directly

After running init, rebuild your native project:

npx expo prebuild --clean

Native Code — Handled Automatically

The library ships an Expo Config Plugin that automatically patches MainApplication.kt during expo prebuild. No manual native code changes needed.

For Expo projects: Just add the plugin to your app.json (the init command does this for you):

{
  "expo": {
    "plugins": ["react-native-github-ota"]
  }
}

For bare React Native projects: The init command patches MainApplication.kt directly. If you need to do it manually, add this:

import java.io.File

// Inside your DefaultReactNativeHost object, add:
override fun getJSBundleFile(): String? {
    val otaBundle = File(applicationContext.filesDir, "ota/index.android.bundle")
    if (!otaBundle.exists()) return null

    // If the APK was updated after the OTA bundle was downloaded, the OTA is stale
    try {
        val appInfo = applicationContext.packageManager.getPackageInfo(applicationContext.packageName, 0)
        if (appInfo.lastUpdateTime > otaBundle.lastModified()) {
            otaBundle.delete()
            File(applicationContext.filesDir, "ota/meta.json").delete()
            return null
        }
    } catch (_: Exception) {}

    return otaBundle.absolutePath
}

This tells React Native: "if an OTA bundle exists on disk and is newer than the installed APK, load it; otherwise use the built-in one." This prevents stale OTA bundles from overriding a newer rebuild.

Manual Setup

If you prefer to set things up manually:

1. Embed Build Info (required)

Before each build, run the embed-commit script to stamp the current git SHA into your app:

node node_modules/react-native-github-ota/scripts/embed-commit.js

Or add it to your build scripts:

{
  "scripts": {
    "embed-commit": "node node_modules/react-native-github-ota/scripts/embed-commit.js",
    "prebuild": "node node_modules/react-native-github-ota/scripts/embed-commit.js && npx expo prebuild"
  }
}

The script creates/updates a constants/buildInfo.ts file in your project root.

2. Add the GitHub Actions Workflow

Copy the workflow template to your project:

mkdir -p .github/workflows
cp node_modules/react-native-github-ota/workflow/ota-bundle.yml .github/workflows/

Or create .github/workflows/ota-bundle.yml manually — see workflow/ota-bundle.yml for the full template.

What the workflow does:

• Triggers on every push to main
• Installs dependencies and embeds the commit hash
• Runs react-native bundle to create the JS bundle
• Creates an ota-manifest.json with commit metadata
• Uploads both files to a GitHub Release tagged ota-latest

Note: The workflow uses GITHUB_TOKEN which is automatically provided by GitHub Actions — no extra secrets needed.

Usage

Configure

Call configureOta once at app startup (e.g. in your root layout):

import { configureOta } from "react-native-github-ota";

configureOta({
  owner: "your-github-username",
  repo: "your-repo-name",
  branch: "main", // optional, default "main"
  releaseTag: "ota-latest", // optional, default "ota-latest"
  bundleFileName: "index.android.bundle", // optional
});

Hook

import { useGithubOta } from "react-native-github-ota";
import { BUILD_INFO } from "./constants/buildInfo";

function MyComponent() {
  const {
    status,
    error,
    updateInfo,
    isChecking,
    isDownloading,
    checkUpdate,
    downloadAndApplyUpdate,
    buildInfo,
  } = useGithubOta({
    autoCheckOnMount: true,
    buildInfo: BUILD_INFO,
    // Optional: control auto-check with your own settings
    shouldAutoCheck: async () => {
      // e.g. read from AsyncStorage
      return true;
    },
  });

  // ...
}

Pre-built Banner

import { OtaUpdateBanner } from "react-native-github-ota";

<OtaUpdateBanner
  visible={bannerVisible}
  status={status}
  error={error}
  updateInfo={updateInfo}
  isDownloading={isDownloading}
  onDownload={downloadAndApplyUpdate}
  onClose={() => setBannerVisible(false)}
  // Optional theme overrides:
  colors={{
    surface: "#1a1a1a",
    text: "#ffffff",
    textSecondary: "#a1a1aa",
    primary: "#3b82f6",
    danger: "#ef4444",
    border: "#27272a",
  }}
/>;

API

configureOta(config)

Option	Type	Default	Description
owner	string	required	GitHub repository owner
repo	string	required	GitHub repository name
branch	string	"main"	Branch to compare against
releaseTag	string	"ota-latest"	Release tag containing the OTA bundle
bundleFileName	string	"index.android.bundle"	Bundle asset filename in the release
autoSettingsKey	string	"@github_ota_settings"	AsyncStorage key for settings

useGithubOta(options)

Option	Type	Default	Description
buildInfo	BuildInfo	required	Build info from embed-commit script
autoCheckOnMount	boolean	true	Auto-check for updates on mount
shouldAutoCheck	() => boolean | Promise<boolean>	—	Guard for auto-check (e.g. user settings)

Returns:

Field	Type	Description
status	string | null	Current status message
error	string | null	Error message if any
isAvailable	boolean	Whether an update is available
isChecking	boolean	Currently checking for updates
isDownloading	boolean	Currently downloading
downloadProgress	number	Download progress (0-100)
updateInfo	UpdateInfo | null	Details about the available update
lastChecked	number | null	Timestamp of last check
checkUpdate	(manual?: boolean) => void	Trigger an update check
downloadAndApplyUpdate	() => void	Download and install the update
setStatus	(s: string | null) => void	Override status message
buildInfo	BuildInfo	The build info passed in

OtaUpdateBanner

A ready-made banner component. Accepts theme colors for dark/light mode support.

npx github-ota-init

CLI command that scaffolds the GitHub Actions workflow, build scripts, config plugin, and native setup into your project. For Expo projects it adds the config plugin to app.json; for bare RN projects it patches MainApplication.kt directly.

License

MIT