# How does it work? (https://hot-updater.dev/docs/concepts/how-it-works)
> Understanding the core infrastructure and update decision logic
## Core Infrastructure
`hot-updater` consists of three key components:
- **Storage**: A place where JavaScript bundles are stored, supporting AWS S3, Cloudflare R2, Supabase Storage, Firebase Storage, etc.
- **Database**: Stores metadata about deployed bundles (version information, etc.) and manages update information.
- **Server**: Determines whether updates are required based on the app's current state, operating through AWS Lambda@Edge, Cloudflare Workers, Supabase Edge Functions, or Firebase Cloud Functions.
Storage and Database are configured using plugins defined in `hot-updater.config.ts`. The Server is initialized and deployed using the `hot-updater init` command.
## Update Decision Logic
`hot-updater` primarily uses UUIDv7 for its operations, with the following update determination process:
### 1. Bundle ID Generation and Management
- Running `hot-updater deploy` invokes the selected build plugin, which generates a UUIDv7-formatted Bundle ID during bundling.
- This Bundle ID includes the deployment timestamp and is uniquely generated per bundle.
### 2. Initial Native App Build
- The first version of the native app does not have an initial Bundle ID, as it isn't created by `hot-updater deploy` but by the native build process.
- In this case, a minimal Bundle ID (`minBundleId`) in UUIDv7 format, based on the app build timestamp, is used.
### 3. Communication with the Update Server
- The app communicates with the server using the current Bundle ID to verify if the bundle is activated (`enabled=true`).
- If the bundle isn't active, the app forcibly updates (rollbacks) to a previously active bundle.
- If an active bundle newer than the current app version exists, the app updates to the latest available bundle.
### 4. Usage of minBundleId
- The `minBundleId` is determined based on the native app's build timestamp.
- The existence of a native app build ensures the embedded bundle is the latest at that point. Bundles older than the `minBundleId` are ignored.
- Every new deployment generates a new Bundle ID, ensuring accurate and reliable updates.
# Plugin System (https://hot-updater.dev/docs/concepts/plugin-system)
> Hot Updater uses a flexible plugin system that lets you customize how bundles are built, stored, and managed to fit your infrastructure.
## Build Plugin
Build plugins handle the bundling process when you run the `hot-updater deploy` command. They generate the JavaScript bundles for your updates.
### Supported Plugins
- **`@hot-updater/bare`**: Runs the project's configured bundler through React Native CLI's `bundle` command.
- **`@hot-updater/rock`**: Runs the project's configured bundler through the `bundle` command in [Rock](https://github.com/callstack/rock) CLI (formerly RNEF).
- **`@hot-updater/expo`**: Executes the bundle command through Expo.
## Storage Plugin
Storage plugins upload your generated bundles during the `hot-updater deploy` command and store them in your chosen storage provider.
Storage plugins expose explicit environment profiles:
- `node`: deploy-time APIs for upload, delete, and local file downloads.
- `runtime`: update-check APIs for HTTP(S) download URLs and small metadata
reads.
`hot-updater.config.ts` uses the `node` profile. `createHotUpdater` uses the
`runtime` profile. Most apps can use the official storage plugins directly;
custom plugin authors only need the profile details when implementing their own
storage provider.
### Supported Plugins
- **`@hot-updater/supabase`**: Provides `supabaseStorage` functionality, leveraging Supabase for storage.
- **`@hot-updater/cloudflare`**: Provides deploy-time `r2Storage` and Worker runtime storage for Cloudflare R2.
- **`@hot-updater/aws`**: Provides `s3Storage` functionality, enabling the use of AWS S3 for storage.
- **`@hot-updater/firebase`**: Provides `firebaseStorage` functionality, utilizing Firebase Storage for storing update bundles.
## Database Plugin
Database plugins store bundle metadata that your app uses to check for updates. They run during the `hot-updater deploy` command.
### Supported Plugins
- **`@hot-updater/supabase`**: Provides `supabaseDatabase` functionality, using Supabase as a database solution.
- **`@hot-updater/aws`**: Provides `s3Database` functionality, utilizing AWS for database storage.
- **`@hot-updater/cloudflare`**: Provides `d1Database` functionality, leveraging Cloudflare D1 for database storage.
- **`@hot-updater/firebase`**: Provides `firebaseDatabase` functionality, using Firebase Firestore for storing update metadata.
# Automatic Rollback (https://hot-updater.dev/docs/concepts/automatic-rollback)
> Hot Updater verifies newly installed bundles on first launch and automatically recovers to a working bundle if startup fails.
## What is Automatic Rollback?
Automatic rollback is the safety mechanism that prevents a bad OTA bundle from trapping users in a crash loop.
When a new bundle is installed, Hot Updater does not trust it immediately. It launches that bundle in a temporary state first, keeps the last known-good bundle as a fallback, and only treats the new bundle as safe after startup succeeds.
This happens automatically when you use `HotUpdater.wrap()`. For custom manual
flows without a root wrapper, call [`HotUpdater.init()`](/docs/react-native-api/init)
when your runtime considers the app ready.
## Core Mechanism
Hot Updater manages two roles during rollout:
- **Staging bundle**: the newly installed bundle waiting to be verified
- **Stable bundle**: the last bundle that was already known to start successfully
The flow is:
1. **Install the update**
- The downloaded bundle becomes the new staging bundle.
- The previously working bundle is kept as the fallback, if one exists.
2. **Launch the staging bundle**
- On the next app start, Hot Updater loads the staging bundle first.
3. **Verify startup**
- If the app reaches its first successful render, the launch is treated as successful.
- The staging bundle becomes the current trusted bundle.
4. **Recover on failure**
- If the app exits or crashes before that point, the staging bundle is treated as failed.
- On the next launch, Hot Updater automatically returns to the last stable bundle.
## What Counts as a Failed Launch?
A bundle is considered failed if it cannot complete startup.
In practice, that means the app never reaches the point where Hot Updater can confirm that the new bundle started successfully.
Typical examples include:
- a JavaScript error during startup
- a native crash while the new bundle is loading
- a fatal error before the first screen appears
This is why Hot Updater must be configured with `HotUpdater.wrap()` or
`HotUpdater.init()` for rollback support. These APIs connect bundle verification
to the app lifecycle.
## What Happens During Rollback?
When rollback happens, Hot Updater:
- stops using the failed staging bundle
- restores the previous stable bundle when one exists
- falls back to the embedded bundle when there is no stable OTA fallback
- records the failed bundle in crash history
This lets users reopen the app normally instead of hitting the same startup failure again.
## Managing Crashed Bundles
Hot Updater keeps a crash history for bundles that failed startup and triggered recovery.
### getCrashHistory()
Returns the bundle IDs that were marked as failed and rolled back.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
function checkCrashedBundles() {
const crashedBundles = HotUpdater.getCrashHistory();
if (crashedBundles.length > 0) {
console.log("Crashed bundles:", crashedBundles);
// Send to your monitoring service
}
}
```
You can use this to:
- monitor deployment health
- identify which bundle IDs failed in production
- send rollback events to analytics or error tracking tools
### clearCrashHistory()
Clears the crash history so a previously failed bundle ID can be retried again.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
async function retryFailedBundle() {
HotUpdater.clearCrashHistory();
console.log("Crash history cleared");
}
```
Only clear crash history after fixing the underlying issue. Otherwise the same broken bundle can be applied again.
### Crash History Blocking
When a bundle fails startup, Hot Updater adds that exact bundle ID to crash history and blocks it from being applied again. This prevents repeated crash loops from the same broken deployment.
To deploy a fixed version:
1. Fix the bug in your code
2. Deploy again with a new bundle ID
3. The new bundle ID bypasses the crash history
If you need to retry the same bundle ID:
1. Verify the bundle is fixed
2. Call `clearCrashHistory()` to reset the blocked list
3. Redeploy the bundle
## In One Sentence
Hot Updater only trusts a new bundle after it launches successfully once. Until then, it keeps a working fallback and can automatically recover if startup fails.
# Introduction (https://hot-updater.dev/docs/get-started/introduction)
> Self-hostable OTA update solution for React Native apps, alternative to CodePush.
## What is Hot Updater?
Hot Updater is a self-hostable OTA (Over-The-Air) update solution for React Native apps. Deploy JavaScript bundle updates instantly without going through app stores.
## Why Hot Updater?
CodePush depended on Microsoft's AppCenter, which had limitations:
- No CDN support, causing slow downloads in some regions
- Only supports Metro bundler, excluding newer alternatives like Re.Pack
- AppCenter has been discontinued
Hot Updater solves these problems with two core principles:
**1. Deploy Anywhere**
Use any infrastructure you want - AWS, Cloudflare, Supabase, Firebase, or your own servers.
**2. Use Any Bundler**
Works with Metro, Re.Pack or any bundler through the plugin system.
## How It Works
Hot Updater uses a [Plugin System](../concepts/plugin-system) that separates concerns:
- **Build Plugins**: Handle bundling (Metro, Re.Pack, Expo, Rock)
- **Storage Plugins**: Store bundles anywhere (S3, R2, Supabase, Firebase)
- **Database Plugins**: Manage metadata (PostgreSQL, D1, Firestore)
This architecture gives you complete control over your deployment infrastructure.
## Key Features
- **Self-Hosting**: Full control over your update infrastructure
- **Multi-Platform**: Seamless iOS and Android support
- **Web Console**: Intuitive update management interface
- **Version Control**: Robust versioning with semantic versioning support
- **Forced Updates**: Push critical updates when needed
- **Channel Management**: Separate environments (dev, staging, production)
- **Fingerprint Strategy**: Automatic native compatibility checking
# Basic Usage (https://hot-updater.dev/docs/get-started/basic-usage)
> This guide walks you through the essential steps to integrate hot-updater into your React Native project.
## Provider Setup
Before configuring the build plugin, you need to set up a provider to handle updates. Hot-updater supports multiple managed providers that handle storage and update distribution.
### Step 1: Install hot-updater
First, install the hot-updater package:
```package-install
npm install hot-updater --save-dev
```
### Step 2: Initialize Your Provider
Run the initialization command to set up your provider interactively:
```package-install
npx hot-updater init
```
This interactive CLI will guide you through:
1. **Build Plugin Selection**: Choose your build system (Bare/React Native CLI, Rock, or Expo)
2. **Provider Selection**: Select from available providers:
- [Supabase](/docs/managed/supabase)
- [Firebase](/docs/managed/firebase)
- [Cloudflare](/docs/managed/cloudflare)
- [AWS](/docs/managed/aws)
3. **Provider Configuration**: Follow provider-specific prompts for authentication and resource setup.
### Step 3: Generated Configuration
After initialization, two files will be generated:
**`.env.hotupdater`** - Contains provider credentials and configuration:
```
# Example for Supabase
HOT_UPDATER_SUPABASE_URL=https://your-project.supabase.co
HOT_UPDATER_SUPABASE_SERVICE_ROLE_KEY=your-service-role-or-secret-key
HOT_UPDATER_SUPABASE_BUCKET_NAME=your-bucket-name
```
**`hot-updater.config.ts`** - Contains provider integration settings:
The example below uses the Bare (React Native CLI) build plugin. If you selected Rock or Expo, only the `build` field changes as shown in the build configuration section below.
```ts title="hot-updater.config.ts"
import { bare } from "@hot-updater/bare";
import { supabaseStorage, supabaseDatabase } from "@hot-updater/supabase";
import { defineConfig } from "hot-updater";
import { config } from "dotenv";
config({ path: ".env.hotupdater" });
export default defineConfig({
build: bare({ enableHermes: true }),
storage: supabaseStorage({
supabaseUrl: process.env.HOT_UPDATER_SUPABASE_URL!,
supabaseServiceRoleKey:
process.env.HOT_UPDATER_SUPABASE_SERVICE_ROLE_KEY!,
bucketName: process.env.HOT_UPDATER_SUPABASE_BUCKET_NAME!,
}),
database: supabaseDatabase({
supabaseUrl: process.env.HOT_UPDATER_SUPABASE_URL!,
supabaseServiceRoleKey:
process.env.HOT_UPDATER_SUPABASE_SERVICE_ROLE_KEY!,
}),
updateStrategy: "appVersion",
});
```
For detailed provider-specific setup instructions, see the [Self-Hosting (Managed)](/docs/managed/supabase) documentation.
The environment variables in `.env.hotupdater` are used only during deployment, not in your app bundle. However, if you're using `react-native-dotenv`, review the [Security guidelines](/docs/policy/security#plugin-token-protection).
### Step 4: Wrap Your Application
Add the HotUpdater wrapper to your main application component:
```tsx title="App.tsx"
import { HotUpdater } from "@hot-updater/react-native";
import { Text, View } from "react-native";
function App() {
return (
Hello World
);
}
export default HotUpdater.wrap({
baseURL: "https://your-update-server-url/api/check-update", // [!code ++]
updateStrategy: "appVersion", // or "fingerprint" // [!code ++]
requestHeaders: {
// Optional: Add custom headers if needed
},
fallbackComponent: ({ progress, status }) => (
{status === "UPDATING" ? "Updating..." : "Checking for Update..."}
{progress > 0 ? (
{Math.round(progress * 100)}%
) : null}
),
})(App);
```
The update server URL will be provided after running `npx hot-updater init`. Check your terminal output or provider console for the correct URL.
## Build Configuration
Hot Updater now configures bundling through the `build` field in `hot-updater.config.ts`. Legacy build-time plugin examples are no longer used.
Use the Bare build plugin for standard React Native CLI projects:
```ts title="hot-updater.config.ts"
import { bare } from "@hot-updater/bare";
import { defineConfig } from "hot-updater";
export default defineConfig({
build: bare({
enableHermes: true,
}),
// ... storage and database
});
```
No additional Babel plugin setup is required.
Use the Rock build plugin for Rock projects:
```ts title="hot-updater.config.ts"
import { rock } from "@hot-updater/rock";
import { defineConfig } from "hot-updater";
export default defineConfig({
build: rock(),
// ... storage and database
});
```
No additional Babel plugin setup is required.
Use the Expo build plugin in `hot-updater.config.ts`:
```ts title="hot-updater.config.ts"
import { expo } from "@hot-updater/expo";
import { defineConfig } from "hot-updater";
export default defineConfig({
build: expo(),
// ... storage and database
});
```
Then add the config plugin to your `app.json`:
```json title="app.json"
{
"expo": {
"plugins": [
[
"@hot-updater/react-native",
{
"channel": "production"
}
]
]
}
}
```
Run prebuild to apply the native changes:
```package-install
npx expo prebuild
```
For Expo projects, the config plugin automatically generates the native code configuration described in the next section.
If you use Expo DOM components (`use dom`), see [Expo DOM Components (`use dom`)](/docs/build-plugins/expo#expo-dom-components-use-dom) for the additional Babel plugin setup.
## Native Code Setup
To complete the integration of `hot-updater`, you'll need to add native code modifications for both Android and iOS platforms. This step ensures the `hot-updater` can interact with your app's underlying framework to apply updates seamlessly.
If you're using Expo with the plugin configured above, this step is handled automatically during prebuild.
### Android
For React Native 0.82 and above, modify your `MainApplication.kt`:
```kt title="android/app/src/main/java/com//MainApplication.kt"
package com.hotupdaterexample
import android.app.Application
import com.facebook.react.PackageList
import com.facebook.react.ReactApplication
import com.facebook.react.ReactHost
import com.facebook.react.ReactNativeApplicationEntryPoint.loadReactNative
import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
import com.hotupdater.HotUpdater
class MainApplication : Application(), ReactApplication {
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 = if (BuildConfig.DEBUG) { // [!code ++]
null // [!code ++]
} else { // [!code ++]
HotUpdater.getJSBundleFile(applicationContext) // [!code ++]
}, // [!code ++]
)
}
override fun onCreate() {
super.onCreate()
loadReactNative(this)
}
}
```
For React Native versions below 0.82, modify your `MainApplication.kt`:
```kt title="android/app/src/main/java/com//MainApplication.kt"
package com.hotupdaterexample
import android.app.Application
import com.facebook.react.PackageList
import com.facebook.react.ReactApplication
import com.facebook.react.ReactHost
import com.facebook.react.ReactNativeHost
import com.facebook.react.ReactPackage
import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint.load
import com.facebook.react.defaults.DefaultReactHost.getDefaultReactHost
import com.facebook.react.defaults.DefaultReactNativeHost
import com.facebook.react.soloader.OpenSourceMergedSoMapping
import com.facebook.soloader.SoLoader
import com.hotupdater.HotUpdater // [!code ++]
class MainApplication : Application(), ReactApplication {
override val reactNativeHost: ReactNativeHost =
object : DefaultReactNativeHost(this) {
override fun getPackages(): List =
PackageList(this).packages.apply {
// Packages that cannot be autolinked yet can be added manually here, for example:
// add(MyReactNativePackage())
}
override fun getJSMainModuleName(): String = "index"
override fun getUseDeveloperSupport(): Boolean = BuildConfig.DEBUG
override val isNewArchEnabled: Boolean = BuildConfig.IS_NEW_ARCHITECTURE_ENABLED
override val isHermesEnabled: Boolean = BuildConfig.IS_HERMES_ENABLED
override fun getJSBundleFile(): String? { // [!code ++]
return if (BuildConfig.DEBUG) { // [!code ++]
null // [!code ++]
} else { // [!code ++]
HotUpdater.getJSBundleFile(applicationContext) // [!code ++]
} // [!code ++]
} // [!code ++]
}
override val reactHost: ReactHost
get() = getDefaultReactHost(applicationContext, reactNativeHost)
override fun onCreate() {
super.onCreate()
SoLoader.init(this, OpenSourceMergedSoMapping)
if (BuildConfig.IS_NEW_ARCHITECTURE_ENABLED) {
// If you opted-in for the New Architecture, we load the native entry point for this app.
load()
}
}
}
```
For Java-based projects, modify your `MainApplication.java`:
```java title="android/app/src/main/java/com//MainApplication.java"
package com.hotupdaterexample;
import android.app.Application;
import com.facebook.react.PackageList;
import com.facebook.react.ReactApplication;
import com.facebook.react.ReactNativeHost;
import com.facebook.react.ReactPackage;
import com.facebook.react.defaults.DefaultNewArchitectureEntryPoint;
import com.facebook.react.defaults.DefaultReactNativeHost;
import com.facebook.soloader.SoLoader;
import java.util.List;
import com.hotupdater.HotUpdater; // [!code ++]
public class MainApplication extends Application implements ReactApplication {
private final ReactNativeHost mReactNativeHost =
new DefaultReactNativeHost(this) {
@Override
public boolean getUseDeveloperSupport() {
return BuildConfig.DEBUG;
}
@Override
protected List getPackages() {
@SuppressWarnings("UnnecessaryLocalVariable")
List packages = new PackageList(this).getPackages();
// Packages that cannot be autolinked yet can be added manually here, for example:
return packages;
}
@Override
protected String getJSMainModuleName() {
return "index";
}
@Override // [!code ++]
protected String getJSBundleFile() { // [!code ++]
return BuildConfig.DEBUG // [!code ++]
? null // [!code ++]
: HotUpdater.Companion.getJSBundleFile(this.getApplication().getApplicationContext()); // [!code ++]
} // [!code ++]
@Override
protected boolean isNewArchEnabled() {
return BuildConfig.IS_NEW_ARCHITECTURE_ENABLED;
}
@Override
protected Boolean isHermesEnabled() {
return BuildConfig.IS_HERMES_ENABLED;
}
};
@Override
public ReactNativeHost getReactNativeHost() {
return mReactNativeHost;
}
@Override
public void onCreate() {
super.onCreate();
SoLoader.init(this, /* native exopackage */ false);
if (BuildConfig.IS_NEW_ARCHITECTURE_ENABLED) {
// If you opted-in for the New Architecture, we load the native entry point for this app.
DefaultNewArchitectureEntryPoint.load();
}
ReactNativeFlipper.initializeFlipper(this, getReactNativeHost().getReactInstanceManager());
}
}
```
### iOS
For Swift projects, modify your `AppDelegate.swift`:
```swift title="ios//AppDelegate.swift"
import UIKit
import React
import React_RCTAppDelegate
import ReactAppDependencyProvider
import HotUpdater // [!code ++]
@main
class AppDelegate: RCTAppDelegate {
override func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
self.moduleName = "HotUpdaterExample"
self.dependencyProvider = RCTAppDependencyProvider()
// You can add your custom initial props in the dictionary below.
// They will be passed down to the ViewController used by React Native.
self.initialProps = [:]
return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
override func sourceURL(for bridge: RCTBridge) -> URL? {
self.bundleURL()
}
override func bundleURL() -> URL? {
#if DEBUG
RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
#else
Bundle.main.url(forResource: "main", withExtension: "jsbundle") // [!code --]
HotUpdater.bundleURL() // [!code ++]
#endif
}
}
```
For Objective-C projects, modify your `AppDelegate.mm`:
```objc title="ios//AppDelegate.mm"
#import "AppDelegate.h"
#import // [!code ++]
#import
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
self.moduleName = @"HotUpdaterExample";
// You can add your custom initial props in the dictionary below.
// They will be passed down to the ViewController used by React Native.
self.initialProps = @{};
return [super application:application didFinishLaunchingWithOptions:launchOptions];
}
- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
{
return [self bundleURL];
}
- (NSURL *)bundleURL
{
#if DEBUG
return [[RCTBundleURLProvider sharedSettings] jsBundleURLForBundleRoot:@"index"];
#else
return [[NSBundle mainBundle] URLForResource:@"main" withExtension:@"jsbundle"]; // [!code --]
return [HotUpdater bundleURL]; // [!code ++]
#endif
}
@end
```
For brownfield apps where the JS bundle is embedded in an XCFramework, you can pass a custom `Bundle` instance to lookup the JavaScript bundle resource: `HotUpdater.bundleURL(bundle: xcframeworkBundle)` in Swift or `[HotUpdater bundleURLWithBundle:xcframeworkBundle]` in Objective-C.
## Next Steps
Now that you've completed the setup, you can start deploying updates:
### Deploy Your First Update
Build and publish an update to your users:
```package-install
npx hot-updater deploy
```
This default command deploys iOS first and Android second. Use `-p ios` or
`-p android` when you want to target only one platform.
Use the interactive mode for guided deployment:
```package-install
npx hot-updater deploy -i
```
For emergency updates with forced reload:
```package-install
npx hot-updater deploy -i -f
```
For staged rollouts, set the initial audience percentage explicitly:
```package-install
npx hot-updater deploy -p ios -r 25
```
### Monitor and Manage Updates
Open the console to track deployments, manage versions, and perform rollbacks:
```package-install
npx hot-updater console
```
### Explore Advanced Features
Learn more about advanced capabilities:
- [App Version Strategy](/docs/guides/update-strategies/app-version) - Target updates by native app version
- [Fingerprint Strategy](/docs/guides/update-strategies/fingerprint) - Target updates by native fingerprint
- [Default Channel Setup](/docs/guides/channel-management) - Configure the app's default release channel
- [Runtime Channel Switch](/docs/guides/runtime-channel-switch) - Temporarily move a device to another channel without rebuilding
- [Simulator Testing](/docs/guides/simulator-test) - Test updates in release mode before production
- [Security Best Practices](/docs/policy/security) - Secure your update infrastructure
# Deploy (https://hot-updater.dev/docs/guides/deploy)
> Deploy an update to one platform or both platforms sequentially.
## Checklist
1. Ensure `hot-updater.config.ts` is properly configured.
2. Wrap your components using `HotUpdater.wrap`.
3. Include the native code.
If you haven't completed these steps, refer to the [Supabase Provider](/docs/managed/supabase) guide.
## Options
```
Options:
-p, --platform specify the platform (choices: "ios", "android")
-t, --target-app-version specify the target app version (semver format e.g. 1.0.0, 1.x.x)
-f, --force-update force update the app (default: false)
-o, --bundle-output-path the directory where bundle archives will be generated
-r, --rollout specify the rollout percentage for the deployed bundle (0-100) (default: 100)
-i, --interactive interactive mode (default: false)
-c, --channel specify the channel to deploy (default: "production")
-m, --message Specify a custom message for this deployment. If not provided, the latest git commit message will be used as the deployment message
-d, --disabled create the bundle in a disabled state (default: false)
-h, --help display help for command
```
## Usage
### Default Mode
When you omit `-p` and `-i`, Hot Updater deploys **iOS first, then Android**
sequentially. If the iOS deploy fails, Android is not attempted.
Run the following command:
```package-install
npx hot-updater deploy
```
- This is the default mode for CI/CD pipelines when both platforms should move
together.
- Local bundle archives are written under platform-specific directories such as
`/ios/bundle/` and `/android/bundle/`.
### Bundle Diffing
New deployments automatically include the artifacts needed for bundle diffing
alongside the archive bundle. When the app runtime supports manifest-based
diffing, unchanged files can be reused locally and only changed files are
downloaded. No deploy flag is required for this behavior.
Deploy also tries to prepare compatible `bsdiff` patches for the Hermes bundle.
Binary patch generation is enabled by default and uses up to three compatible
base bundles. Set `patch.enabled: false` to disable it, or change
`patch.maxBaseBundles` from its default of `3`. Patch generation is best-effort;
a skipped patch does not fail the deployment because the normal archive update
remains available.
See [Bundle Diffing](/docs/guides/bundle-diffing) for the runtime behavior and
fallback rules.
### Interactive Mode
Interactive mode guides you through the deployment steps via keyboard inputs.
Execute the following command:
```package-install
npx hot-updater deploy -i
```
The `-i` (or `--interactive`) flag enables interactive keyboard input.
- This mode allows you to proceed through deployment steps interactively.
### For Continuous Deployment (CD) Pipelines
Use this mode when a pipeline should deploy only one platform.
Run the following command:
```package-install
npx hot-updater deploy -p <"ios" | "android">
```
- Use `-p` to scope the deploy to exactly one platform.
### Force Update
Deploy a forced update for emergency purposes. This will immediately apply the update.
Run the following command:
```package-install
npx hot-updater deploy -p <"ios" | "android"> -f
```
The `-f` (or `--force-update`) flag enables force update.
### Channel
The `-c` (or `--channel`) flag specifies the release channel.
Run the following command:
```package-install
npx hot-updater deploy -p <"ios" | "android"> -c ""
```
The `-c` (or `--channel`) flag specifies the release channel. The default value is `production`.
For more details about default channels, refer to
[Default Channel Setup](/docs/guides/channel-management).
### Rollout
The `-r` (or `--rollout`) flag sets the rollout percentage for the deployed
bundle.
Run the following command:
```package-install
npx hot-updater deploy -p <"ios" | "android"> -r 25
```
Use `1` to `99` for gradual rollout, `100` for a full rollout, and `0` when
you want to keep the bundle deployed but unavailable to numeric rollout until
you edit it later in the console.
Hot Updater maps rollout percentages to `1..1000` numeric cohorts internally.
For example, `-r 25` means 250 of 1000 numeric cohorts are eligible for that
bundle.
If you omit `-r`, the default value is `100`, so the bundle is deployed to the
entire audience immediately.
For more on gradual rollout, current device cohorts, and cohort targeting from
the console, see [Rollout & Cohorts](/docs/guides/rollout-cohorts).
### Message
The `-m` (or `--message`) flag specifies the message.
Run the following command:
```package-install
npx hot-updater deploy -p <"ios" | "android"> -m ""
```
If you omit `-p`, the same message is applied to both sequential platform
deploys.
## Force Update Flag Difference
| Update Type | When Applied | How to Enable |
| ------------ | -------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Default | Downloads the update bundle in the background and applies it when the user restarts the app. | Default setting |
| Force Update | Downloads the update bundle and applies it immediately. | Use the `--force-update` flag or console. |
# Custom Update (https://hot-updater.dev/docs/guides/custom-update)
> Build a custom Hot Updater client flow with init, checkForUpdate, updateBundle, and reload.
## Overview
Hot Updater can manage updates automatically with `HotUpdater.wrap`, but you can
also build the client flow yourself. A custom flow is useful when you want to
check only after login, gate updates by app state, coordinate with navigation
state, or let another runtime own the root component.
The custom flow has four parts:
1. Initialize Hot Updater with `HotUpdater.init`.
2. Decide when to call `HotUpdater.checkForUpdate`.
3. Download the bundle with `updateInfo.updateBundle()` or
`HotUpdater.updateBundle`.
4. Reload immediately or later.
## Initialize
Use `HotUpdater.init` when you do not want to wrap the root component.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
HotUpdater.init({
baseURL: "",
requestHeaders: {
Authorization: "Bearer ",
},
onError: error => {
console.error("Hot Updater failed", error);
},
});
```
`HotUpdater.init` has the same initialization effect as manual `wrap`, without
creating an unnecessary React HOC.
```tsx
HotUpdater.init({
baseURL: "",
});
export default App;
```
This configures Hot Updater and notifies the update server that the current app
launch is ready.
## Check on Your Schedule
Call `checkForUpdate` only when your app is ready for the decision.
```tsx
async function checkForAppUpdate() {
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
});
if (!updateInfo) {
return { status: "UP_TO_DATE" as const };
}
return updateInfo;
}
```
Common places to check:
- After authentication finishes
- After the first screen becomes interactive
- When the app returns to foreground
- Behind a remote-config or staged rollout gate
- From a user-facing "Check for updates" action
## Download and Apply
The return value includes an `updateBundle` helper with all required update
metadata pre-filled.
```tsx
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
});
if (updateInfo) {
const downloaded = await updateInfo.updateBundle();
if (downloaded && updateInfo.shouldForceUpdate) {
await HotUpdater.reload();
}
}
```
For non-force updates, you can download in the background and reload later.
```tsx
if (updateInfo && !updateInfo.shouldForceUpdate) {
await updateInfo.updateBundle();
// Later, after navigation is idle or the user accepts a prompt:
await HotUpdater.reload();
}
```
## Show Update Progress
Use `useHotUpdaterStore` when you want to render download progress in a
component. The store is updated from Hot Updater progress events.
```tsx
import { HotUpdater, useHotUpdaterStore } from "@hot-updater/react-native";
import { useEffect, useState } from "react";
import { Pressable, Text, View } from "react-native";
type AppUpdateInfo = Awaited>;
type AppUpdateState = {
status: "checking" | "current" | "downloading" | "ready" | "updating" | "error";
updateInfo: AppUpdateInfo;
};
function SettingsUpdateRow() {
const progress = useHotUpdaterStore((state) => state.progress);
const [appVersion] = useState(() => HotUpdater.getAppVersion() ?? "1.0.0");
const [appUpdate, setAppUpdate] = useState({
status: "checking",
updateInfo: null,
});
useEffect(() => {
let isActive = true;
async function prepareUpdate() {
try {
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
});
if (!isActive) {
return;
}
if (!updateInfo) {
setAppUpdate({ status: "current", updateInfo: null });
return;
}
setAppUpdate({ status: "downloading", updateInfo });
const didDownload = await updateInfo.updateBundle();
if (!isActive) {
return;
}
setAppUpdate({
status: didDownload ? "ready" : "error",
updateInfo: didDownload ? updateInfo : null,
});
} catch {
if (isActive) {
setAppUpdate({ status: "error", updateInfo: null });
}
}
}
void prepareUpdate();
return () => {
isActive = false;
};
}, []);
async function applyUpdate() {
if (appUpdate.status !== "ready") {
return;
}
setAppUpdate((current) => ({ ...current, status: "updating" }));
try {
await HotUpdater.reload();
} catch {
setAppUpdate((current) => ({ ...current, status: "error" }));
}
}
const statusText =
appUpdate.status === "checking"
? "checking"
: appUpdate.status === "current"
? "current"
: appUpdate.status === "downloading"
? `downloading ${Math.round(progress * 100)}%`
: appUpdate.status === "ready"
? "restart ready"
: appUpdate.status === "updating"
? "restarting"
: "check failed";
return (
Version {appVersion}{statusText}
{appUpdate.status === "downloading" ||
appUpdate.status === "ready" ||
appUpdate.status === "updating" ? (
void applyUpdate()}
>
{appUpdate.status === "updating" ? "Restarting" : "Restart"}
) : null}
{appUpdate.status === "ready" && appUpdate.updateInfo?.message ? (
{appUpdate.updateInfo.message}
) : null}
);
}
```
Use `addListener` when you need to react to the raw event directly.
```tsx
import { useEffect, useState } from "react";
import { HotUpdater } from "@hot-updater/react-native";
import { Text } from "react-native";
function UpdateProgressLabel() {
const [progress, setProgress] = useState(0);
useEffect(() => {
const unsubscribe = HotUpdater.addListener("onProgress", (event) => {
setProgress(event.progress);
});
return unsubscribe;
}, []);
return {Math.round(progress * 100)}%;
}
```
## Runtime Channel Checks
Custom flows can switch channels at check time. The switch is persisted only
after the returned update is applied.
```tsx
const updateInfo = await HotUpdater.checkForUpdate({
channel: "beta",
updateStrategy: "appVersion",
});
if (updateInfo) {
await updateInfo.updateBundle();
await HotUpdater.reload();
}
```
To return to the build-time channel, call `HotUpdater.resetChannel()`.
```tsx
const reset = await HotUpdater.resetChannel();
if (reset) {
await HotUpdater.reload();
}
```
## Error Handling
Wrap your custom flow in one boundary and keep the app usable when an update
check fails.
```tsx
async function runUpdateFlow() {
try {
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
});
if (!updateInfo) {
return;
}
const downloaded = await updateInfo.updateBundle();
if (downloaded && updateInfo.shouldForceUpdate) {
await HotUpdater.reload();
}
} catch (error) {
reportUpdateError(error);
}
}
```
## Checklist
- Call `HotUpdater.init` before update APIs.
- Keep `notifyAppReady` wired through `baseURL`.
- Choose the check timing based on your app state, not module import order.
- Download with `updateInfo.updateBundle()` unless you need direct control.
- Use `useHotUpdaterStore` or `addListener` to show update progress.
- Use `reload()` immediately only for force updates or explicit user consent.
- Add error reporting around the full flow.
## Related
- [`HotUpdater.init()`](/docs/react-native-api/init)
- [`HotUpdater.wrap()`](/docs/react-native-api/wrap)
- [`HotUpdater.checkForUpdate()`](/docs/react-native-api/checkForUpdate)
- [`HotUpdater.reload()`](/docs/react-native-api/reload)
- [`HotUpdater.addListener()`](/docs/react-native-api/addListener)
- [`useHotUpdaterStore()`](/docs/react-native-api/useHotUpdaterStore)
# Bundle Diffing (https://hot-updater.dev/docs/guides/bundle-diffing)
> Ship smaller OTA updates by reusing unchanged bundle files.
## What it is
> Bundle diffing means: do not download the whole OTA archive again when the
> device can reuse files it already has.
Think of an OTA bundle as a folder of files installed on the device.
```txt
First OTA update:
download compressed archive -> install OTA bundle
Later OTA update:
local unchanged files
+ downloaded changed files
+ optional Hermes patch
-> next OTA bundle
```
What the device downloads depends on what changed:
| When this happens | What the device downloads |
| --- | --- |
| First OTA after native install | Normal compressed archive |
| Later OTA, unchanged file | Nothing; the file is copied locally |
| Later OTA, changed regular asset | Complete new asset file |
| Later OTA, changed Hermes bundle file | `.bsdiff` patch when available, otherwise the complete new Hermes bundle file |
For example, an update that would otherwise download a **10 MB archive** might
only need to download a **600 KB patch file** when the byte-level Hermes changes
are small.
Those numbers are only an example. The archive and the patch file are different
artifacts, and the patch file size always depends on what changed between the
two bundles. Large or widespread changes can still produce a much larger patch.
You do not need to change your update-check code or deploy command. After your
app is using a diff-enabled Hot Updater runtime, new deployments include the
data needed for bundle diffing automatically.
### Two layers
Bundle diffing has two separate optimizations:
1. **File reuse for the whole OTA bundle.** Files that already exist locally can
be copied into the next OTA bundle. This applies to regular assets and the
Hermes bundle file.
2. **Binary patches for changed Hermes bundles.** If the Hermes bundle changed
and Hot Updater has a matching `.bsdiff` patch, the app can download the
patch instead of the complete new Hermes bundle file.
The key difference is that assets are reused at the file level, while changed
Hermes bundles can also be patched at the byte level.
| File type | If unchanged | If changed |
| --- | --- | --- |
| Regular asset | Copy local file | Download the complete new asset file |
| Hermes bundle file | Copy local file | Apply `.bsdiff` patch, then fallback to the complete new Hermes bundle file |
Regular assets include files such as images and fonts. They are not binary
patched; if they changed, the complete new asset file is downloaded. The Hermes
bundle is the only file type that gets the extra `.bsdiff` patch optimization.
## How to use it
No special command is required:
```bash
npx hot-updater deploy -p ios
npx hot-updater deploy -p android
```
For apps running a bundle-diffing capable runtime, that is enough to enable
manifest-based diffing.
A diff-enabled runtime means the native app was built with a Hot Updater version
that includes bundle diffing support.
Hermes binary patch optimization is also enabled by default:
```ts title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
patch: {
enabled: true,
maxBaseBundles: 3,
},
});
```
This is the default behavior. Add the `patch` block only when you want to
override it, for example to disable binary patch generation or change how many
previous OTA bundles are used as patch bases.
| Option | Default | Meaning |
| --- | --- | --- |
| `patch.enabled` | `true` | Generates `.bsdiff` patches for changed Hermes bundles. |
| `patch.maxBaseBundles` | `3` | Uses up to this many previous compatible OTA bundles as patch bases. |
### Binary patches
Binary patches are an extra optimization for Hermes bundle files:
- During deploy, Hot Updater creates a `.bsdiff` patch between a previous
Hermes bundle and the new Hermes bundle.
- At runtime, the app downloads that patch and applies it to the
already-installed Hermes bundle with the `bspatch` algorithm.
- The result is the new Hermes bundle file, without downloading that complete
file.
This does not replace manifest-based file reuse. Regular assets are still
copied from the current OTA bundle or downloaded as complete new files.
`maxBaseBundles` controls how many previous compatible OTA bundles are used as
patch bases when deploying a new OTA update.
For example:
```txt
Base bundle -> OTA A -> OTA B -> OTA C
```
When deploying `OTA C` with `maxBaseBundles: 2`, Hot Updater can prepare patches
from:
- `OTA B` to `OTA C`
- `OTA A` to `OTA C`
This means devices currently on `OTA A` or `OTA B` can download a small patch to
`OTA C` instead of the complete new Hermes bundle file. Devices that only have
the base bundle still use the compressed archive for their first OTA update.
Devices on an older OTA outside the selected patch bases download the complete
new Hermes bundle file instead of a patch.
Notes:
- Defaults to `3`.
- Compatible patch bases are older enabled bundles from the same channel and
platform.
- Hot Updater also matches by fingerprint when fingerprinting is used, or by
target app version when fingerprinting is not used.
- Higher values increase the range of OTA versions covered by patches, but can
make deployment time and storage work grow roughly with the number of
selected base bundles because more patch artifacts must be generated.
If a patch cannot be created, Hot Updater still deploys the normal OTA update.
Patch generation is an optimization, not a requirement for delivery.
## How it works
### During deploy
Hot Updater prepares both the normal delivery path and the diffing data:
- Uploads the normal OTA archive.
- Uploads the manifest and per-file manifest assets.
- Records manifest and asset storage metadata.
- Creates `.bsdiff` patch files for changed Hermes bundles when binary patching
is enabled.
### First OTA update
The first OTA update after installing the native app downloads the normal
compressed archive.
There is no older OTA bundle on the device yet, so Hot Updater cannot copy local
files or apply a patch.
### Later OTA updates
After that, updates can be assembled from smaller pieces:
1. The app reads the new update manifest.
2. Files that already exist in the current OTA bundle are copied locally.
3. Files that are new or changed are downloaded.
4. For the Hermes bundle, the app first checks whether there is a `.bsdiff`
patch that matches the currently installed OTA bundle.
5. If the patch matches, the app downloads the patch and applies it to the
existing Hermes bundle to produce the new Hermes bundle.
### Verification and fallback
Before using a patched Hermes bundle, the app verifies:
- the base file hash
- the patch file hash
- the final output hash
If anything does not match, or if the patch cannot be applied, Hot Updater
downloads the complete new Hermes bundle file when that file URL is available.
If the changed file cannot be downloaded, or if manifest-driven installation
cannot be used, it falls back to the normal compressed archive.
### Inspect downloaded files
Use `useHotUpdaterStore` when you want to check which files were downloaded
during a bundle diffing update.
Use `progress` for the overall update progress. Use `details.files` for
per-file progress during manifest-based diffing.
Per-file details are available only when `artifactType` is `"diff"`. When
`artifactType` is `"archive"`, the app is downloading one compressed archive, so
there is no per-file progress list.
```tsx
import { Text, View } from "react-native";
import { useHotUpdaterStore } from "@hot-updater/react-native";
function UpdateDownloadProgress() {
const { artifactType, details, progress } = useHotUpdaterStore();
const files = artifactType === "diff" ? (details?.files ?? []) : [];
return (
Overall progress: {Math.round(progress * 100)}%
{artifactType === "archive" ? (
Downloading the normal OTA archive
) : null}
{artifactType === "diff" && details ? (
Changed files: {details.completedFilesCount}/
{details.totalFilesCount}
{files.map((file) => (
{file.path}
{file.status} · {Math.round(file.progress * 100)}%
{file.downloadPath !== file.path ? (
Downloaded artifact: {file.downloadPath}
) : null}
))}
) : null}
);
}
```
In `details.files`, `path` is the final file path inside the OTA bundle.
`downloadPath` is the artifact that was transferred. They are usually the same,
but can differ when Hot Updater downloads an intermediate artifact such as a
`.bsdiff` patch.
## Signing
Bundle diffing works without signing, but signing is recommended. When signing
is enabled, the archive, manifest, and manifest assets are verified before the
update is installed.
See [Bundle Signing](/docs/guides/bundle-signing) for setup.
# Rollout & Cohorts (https://hot-updater.dev/docs/guides/rollout-cohorts)
> Gradually roll out bundles from 1% to 100%, inspect the active cohort on device, and target specific cohorts from the console.
## Overview
Hot Updater uses cohorts to decide whether a device is eligible for a bundle.
- Every install gets a persisted numeric cohort from `1` to `1000`.
- `npx hot-updater deploy -r ` maps `1..100` to those numeric
cohorts.
- Omitting `-r` uses `100`, which is a full rollout.
- `-r 0` is also valid when you want to deploy a bundle without exposing it to
numeric rollout yet.
- Custom cohorts such as `qa`, `dogfood`, or `vip-testers` can be assigned
directly on the device.
Percentage rollout applies only to numeric cohorts. Custom cohorts do not
participate in percentage rollout on their own. To keep a custom cohort such
as `qa` receiving the same bundle alongside numeric rollout, add it to `Target
Cohorts`.
## Deploy a Bundle with RollOut
Use `-r` during deploy:
```package-install
npx hot-updater deploy -p ios -r 10
npx hot-updater deploy -p ios -r 25
npx hot-updater deploy -p ios -r 100
```
- `-r 10` targets 100 of 1000 numeric cohorts.
- `-r 25` targets 250 of 1000 numeric cohorts.
- `-r 100`, or omitting `-r`, targets the full audience.
Hot Updater keeps the selected numeric cohort set stable per bundle. That means
increasing a bundle from `10%` to `25%` expands the same bundle's eligible set
instead of reshuffling everyone.
## Scenario 1: Numeric Rollout Flow
This scenario covers the normal numeric rollout flow.
In this scenario, assume `HotUpdater.getCohort()` returns `411`.
### See the Current Cohort on Device
Check the current device cohort with `HotUpdater.getCohort()`:
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { Text } from "react-native";
export function CohortStatus() {
return HotUpdater.getCohort(): {HotUpdater.getCohort()};
}
```
This is the device state before rollout:
In this example, `HotUpdater.getCohort()` returns `411`, so this device belongs
to cohort `411`.
### Preview the Selected Numeric Cohorts
Assume you deploy the bundle with a `50%` rollout:
```package-install
npx hot-updater deploy -p ios -r 50
```
Open the bundle in the console and click `Preview Cohorts`:
This opens the numeric cohort preview for that bundle:
If rollout is `50.0%`, Hot Updater selects `500` numeric cohorts out of
`1..1000`. That selection is based on the bundle's `bundleId`, so the result is
stable for that bundle.
`50%` rollout does not mean cohorts `1..500`. Hot Updater uses a stable
shuffled set per bundle, and `Preview Cohorts` shows the exact numeric cohorts
selected for that rollout.
You can read the result like this:
| Check | Example | Result |
| ---------------------------- | --------------------------------- | ------------------------------------------------------ |
| Device cohort | `HotUpdater.getCohort() = 411` | This device belongs to cohort `411`. |
| Rollout percentage | `50.0%` | The bundle targets `500` of `1000` numeric cohorts. |
| Cohort excluded from preview | `410` is not in the selected list | A device in cohort `410` does not receive this bundle. |
| Cohort included in preview | `411` is in the selected list | A device in cohort `411` does receive this bundle. |
Here is the direct check for cohort `411`:
In this example, cohort `411` is included in the selected rollout set. Since
the iOS example app above reported `HotUpdater.getCohort(): 411`, this device
is eligible for the rollout and will receive the bundle.
After the app checks for updates and applies the eligible bundle, you end up
with the post-update state below:
This walkthrough shows the normal numeric rollout flow:
1. The device starts with cohort `411`.
2. You deploy with `npx hot-updater deploy -p ios -r 50`.
3. The preview confirms that cohort `411` is included.
4. The device is eligible, so it receives the bundle.
This is why the preview is useful: percentage rollout is not a simple `1..500`
range. Hot Updater keeps a stable shuffled set per bundle, and `Preview
Cohorts` shows the exact numeric cohorts included in that rollout.
## Scenario 2: Manual Cohort Override and Target Cohorts
Use this flow when you want a fixed tester group to keep receiving the bundle
while numeric rollout continues for the rest of the audience.
This is useful because numeric rollout picks a stable but bundle-specific
numeric cohort set. A tester device may or may not be in that set.
`Target Cohorts` lets you keep a known group such as `qa` included throughout
rollout.
In this example, tester devices use cohort `qa`, and the bundle keeps
`Rollout Percentage = 50.0%` while also targeting `qa`.
You can use the same flow with a numeric cohort such as `411`.
This is the device state after setting the cohort to `qa`:
In this example, the app UI shows `HotUpdater.getCohort() = qa`.
### Set the Device Cohort
Use `HotUpdater.setCohort()` to make the device act like a specific cohort:
```tsx
import { HotUpdater } from "@hot-updater/react-native";
function assignQaCohort() {
HotUpdater.setCohort("qa");
console.log("Active cohort:", HotUpdater.getCohort());
}
```
```tsx
import { HotUpdater } from "@hot-updater/react-native";
function assignNumericCohort() {
HotUpdater.setCohort("411");
console.log("Active cohort:", HotUpdater.getCohort());
}
```
You can set either kind of cohort:
- `HotUpdater.setCohort("qa")` puts the device in a named tester group.
- `HotUpdater.setCohort("411")` makes the device behave like numeric cohort
`411`.
- A numeric override is useful when you want a tester device to follow a bundle
that is already rolling out to a known numeric cohort.
If you want to restore the original cohort later, read it with
`HotUpdater.getCohort()` and save it before calling `setCohort()`.
### Target Specific Cohorts from the Console
If you want numeric rollout and a fixed tester group at the same time, keep
both on the same bundle. A common flow is:
1. Deploy the bundle with `-r 0`.
2. Add `qa` to `Target Cohorts`.
3. After QA verifies the bundle, increase the same bundle to `50%` rollout.
You can do the same thing from the CLI:
```package-install
npx hot-updater bundle update --target-cohorts qa -y
npx hot-updater bundle update --rollout-cohort-count 500 -y
```
`--rollout-cohort-count 500` is equivalent to a `50%` rollout because Hot
Updater uses 1000 numeric cohorts.
After QA verifies the bundle and you raise the same bundle to `50%`, the
console can look like this:
In this example, the bundle is configured like this:
- `Rollout Percentage = 50.0%`
- `Target Cohorts = qa`
`Target Cohorts` supports both custom cohorts like `qa` and numeric values like
`411`. Think of it as an explicit cohort list: you can put existing numeric
cohorts and custom cohorts in the same place.
`Rollout Percentage` and `Target Cohorts` work together.
- Numeric rollout still applies to the selected numeric cohorts for this
bundle.
- `Target Cohorts` adds extra cohorts such as `qa` or `411`.
You may see both settings in the console at the same time, as in the screenshot
above. In this state, the numeric `50.0%` rollout still applies to the bundle's
selected numeric cohorts, and devices in `qa` are also included.
This is useful in two common cases:
- Deploy with `-r 0` and `Target Cohorts = qa` when you want to test the bundle
with QA first.
- Raise the same bundle to `50%` later and keep `qa` in `Target Cohorts` so
the main rollout and QA testing continue together.
You can read the result like this:
| Check | Example | Result |
| ------------------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Numeric rollout device | `HotUpdater.getCohort() = 411`, and `411` is in `Preview Cohorts` | This device receives the bundle through numeric rollout. |
| QA tester device | `HotUpdater.getCohort() = qa` | This device receives the bundle because `qa` is in `Target Cohorts`. |
| Numeric cohort outside rollout | `HotUpdater.getCohort() = 410`, and `410` is not in `Preview Cohorts` | This device does not receive the bundle unless `410` is also added to `Target Cohorts`. |
| Other custom cohort | `HotUpdater.getCohort() = dogfood` | This device does not receive the bundle unless `dogfood` is targeted. |
Use this flow when you want stable tester coverage without giving up gradual
numeric rollout. If needed, you can do the same thing with a numeric cohort
such as `411`.
### Manual Override Flow
1. Read the current cohort on the tester device with `HotUpdater.getCohort()`.
2. Change it to `qa` with `HotUpdater.setCohort()`. If you want to match a
numeric rollout instead, use a value such as `411`.
3. Deploy the bundle with `npx hot-updater deploy -p ios -r 0` and set
`Target Cohorts = qa` so only QA devices receive it first.
4. After QA confirms the bundle, increase rollout to `50%` and keep `qa` in
`Target Cohorts` on the same bundle.
5. Devices in the selected numeric rollout keep receiving the bundle, and QA
devices in `qa` also keep receiving it.
## Related APIs
- [`HotUpdater.getCohort()`](/docs/react-native-api/getCohort)
- [`HotUpdater.setCohort()`](/docs/react-native-api/setCohort)
- [Deploy](/docs/guides/deploy)
- [Console](/docs/guides/console)
# Console (Rollback & Force Update) (https://hot-updater.dev/docs/guides/console)
> Opens a localhost server based on plugins configured in `hot-updater.config.ts`. For security reasons, only localhost server is supported at the moment.
**The console provides the following features:**
- Rollback
- Force update flag
- Quick access to git history for updates
## Configuration (Optional)
This is a console configuration that does not affect the bundle.
You can configure additional console settings in the `hot-updater.config.ts` file.
The `storage` and `database` plugins must be exist.
| Option | Description | Default |
| ---------------- | -------------------------------------------------------- | ------- |
| `console.gitUrl` | Enables commit shortcuts by linking to git commit hashes | - |
| `console.port` | Sets the console server port | `1422` |
```ts title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
console: { // [!code hl]
port: 3000, // [!code hl]
}, // [!code hl]
build: ...,
storage: ...,
database: ...,
});
```
## Usage
Execute the following command:
```package-install
npx hot-updater console
```
You can also use the bundle CLI for automation and CI scripts:
```package-install
npx hot-updater bundle list -p ios
npx hot-updater bundle show
npx hot-updater bundle disable -y
npx hot-updater bundle enable -y
npx hot-updater bundle update --force-update true -y
npx hot-updater bundle update --rollout-cohort-count 500 -y
npx hot-updater bundle update --target-cohorts qa,dogfood -y
```
Add `--json` to `bundle list`, `bundle show`, or `bundle update` when another
tool needs to read the raw bundle data.
After deleting bundle records, use the [Storage Cleanup](/docs/guides/storage-cleanup)
workflow to preview and reclaim bundle objects and shared assets that are no
longer referenced.
## Rollback
When you set a bundle's `enabled` status to `false` in the console, users who have that bundle will immediately force update to the **previous bundle**.
## Force Update
When you set a bundle's `shouldForceUpdate` status to `true` in the console, users who have that bundle will immediately force update to the **latest bundle**.
## Git URL
You can set the git URL in the `hot-updater.config.ts` file.
```ts title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
console: {
gitUrl: "", // e.g. https://github.com/gronxb/hot-updater // [!code hl]
},
});
```
When you set the git URL, the commit hash will be clickable and redirect you to the corresponding commit in your repository.
# Storage Cleanup (https://hot-updater.dev/docs/guides/storage-cleanup)
> Safely reclaim unreferenced bundle artifacts and shared assets with the storage prune command.
## How pruning works
`hot-updater storage prune` is reference-aware garbage collection. It reads all
bundle records and their manifests, lists the configured storage prefix, and
selects only objects that are no longer referenced.
It can remove:
- Orphaned bundle objects in both the legacy `/...` layout and the
current `bundles//...` layout.
- Unreferenced content-addressed assets under `assets/sha256/...`.
Live bundle objects, referenced assets, recently modified objects, objects
without a modification timestamp, and unknown files are protected.
Pruning is not a retention policy. Upgrading Hot Updater fixes new S3
management scans without deleting live bundle records. Delete records you no
longer need before pruning their objects.
## Select old bundle records
List the records you intend to remove. Narrow the result by channel, platform,
or exact target app version as needed:
```package-install
npx hot-updater bundle list --channel production --platform ios --target-app-version 1.0.0 --limit 100 --json
```
Delete one or more selected records:
```package-install
npx hot-updater bundle delete --yes
```
`bundle delete` removes database records. Shared assets and bundle files remain
until a reference-aware prune confirms that no remaining record uses them.
## Preview eligible objects
Run an explicit dry run first:
```package-install
npx hot-updater storage prune --dry-run
```
The preview shows each eligible object, its modification time, size, type, and
the total reclaimable size. The command fails closed if it cannot load all
bundle references or required manifests.
The default `--protect-newer-than 24h` window compares the current time with
each object's storage `lastModified` timestamp. It does **not** measure time
since the bundle record was deleted. Increase the window when deployments may
remain in flight for longer:
```package-install
npx hot-updater storage prune --dry-run --protect-newer-than 7d
```
Durations accept `m`, `h`, `d`, or `w`, such as `30m`, `24h`, `7d`, or `2w`.
## Delete eligible objects
Pause every deploy and promote process that writes to the same storage prefix,
then run:
```package-install
npx hot-updater storage prune --protect-newer-than 24h --yes
```
Before deletion, Hot Updater reloads bundle and manifest references and removes
objects from the candidate set if they became live.
The configured database must own every object under the configured storage
prefix. If databases or environments share a bucket, assign each one a
separate storage `basePath` before pruning.
Storage pruning currently requires the management capabilities provided by
`s3Storage`, including AWS S3 and S3-compatible services such as Cloudflare R2.
# AI Agent Guide (https://hot-updater.dev/docs/guides/ai-agents)
> Use the Hot Updater skill with AI coding agents and ask for OTA operations in natural language.
## Attach the Skill
Agent skills are packaged capabilities that give AI coding agents structured
instructions for a production workflow. Attach the Hot Updater skill from its
GitHub location:
- [`skills/hot-updater/SKILL.md`](https://github.com/hot-updater/skills/blob/main/skills/hot-updater/SKILL.md)
You can also install it with `npx skills`:
```sh
npx skills add hot-updater/skills
```
## Ask With `$hot-updater`
After attaching the skill, ask your agent in natural language:
```txt
$hot-updater deploy using the current app version
$hot-updater deploy the current iOS app version to production
$hot-updater roll back the most recently deployed bundle
$hot-updater list iOS bundles on the production channel
$hot-updater run doctor with server URL https://updates.example.com/api/check-update
$hot-updater fix local doctor issues that do not require server credentials
```
The skill gives the agent enough CLI context to translate those requests into
safe `npx hot-updater ...` flows.
## Safety Rules
- The agent should not run `npx hot-updater init` for you. `init` is
interactive and asks for project-specific provider and build choices, so run
it directly in your terminal.
- The agent should ask for the update server URL before running a
server/infrastructure doctor check unless you already provided it or it is
obvious from local configuration.
- When iterating on doctor failures, the agent should prefer
`npx hot-updater doctor --json`. It should repair issues marked
`fixability: "auto"`, run listed commands for `fixability: "command"`, and
stop on `fixability: "blocked"`.
- The agent should not edit provider credentials unless you explicitly ask it
to. Credentials are commonly stored in `.env.hotupdater`, but projects may
use a different environment-loading setup.
- Server infrastructure failures are usually blocked because migrations and
redeploys need provider environment variables or deployment access. The agent
should summarize those blockers instead of attempting to mutate server state.
- If a deploy fails, the agent should not keep trying fixes or mutate project
setup automatically. It should summarize the failed command, the likely
cause, and the next checks for you to decide.
- For state-changing operations such as deploy, rollback, enable, disable, or
database migration, the agent should identify the target first and verify the
result afterward.
# Simulate Test (https://hot-updater.dev/docs/guides/simulator-test)
> Since hot-updater does not work in dev environment, you need to test it in Release mode as shown below.
## Checklist
- Make sure `hot-updater.config.ts` is properly configured.
- Make sure `HotUpdater.wrap` is properly implemented.
## Step 1: Simulator Release Mode
Run your app in Release mode to test hot-updater (it doesn't work in dev mode).
**iOS:**
```sh
cd ios && pod install && cd ..
npx react-native run-ios --mode Release
```
**Android:**
```sh
npx react-native run-android --mode Release
```
**iOS:**
```sh
npx rock run:ios --configuration Release
```
**Android:**
```sh
npx rock run:android --variant Release
```
**iOS:**
```sh
npx expo run:ios --configuration Release
```
**Android:**
```sh
npx expo run:android --variant release
```
## Step 2: Deploy
Deploy with interactive mode and force update flag enabled in hot-updater deploy mode.
When [HotUpdater.wrap](/docs/react-native-api/wrap) is set up, updates will be applied when you restart the app.
You can check the update progress status using [useHotUpdaterStore](/docs/react-native-api/useHotUpdaterStore).
### For Normal Deployment
This is the standard deployment mode. After an update is created, users need to restart their app after downloading the bundle for the update to take effect.
```package-install
npx hot-updater deploy -i
```
### For Emergency Deployment
This is the emergency deployment mode. After an update is created, the bundle will automatically reload and apply the update as soon as users download it.
```package-install
npx hot-updater deploy -i --force-update
```
## Step 3: Rollback
When you set a bundle's `enabled` status to `false` in the console, users who have that bundle will immediately force update to the **previous bundle**.
Open the console and set the bundle's `enabled` status to `false`.
```package-install
npx hot-updater console
```
# Default Channel Setup (https://hot-updater.dev/docs/guides/channel-management)
> Set the default release channel embedded in your native app and deploy updates to that channel.
## Overview
The default channel is the release channel embedded in your native app at build time.
- Apps use `production` when no channel is specified.
- This channel decides where the app checks for updates by default.
- Changing the default channel requires rebuilding the native app.
Need to temporarily move a device to another channel without rebuilding? See
[Runtime Channel Switch](/docs/guides/runtime-channel-switch).
## Set the Default Channel
### 1. Specify the Channel in Native Configuration
Use the `hot-updater channel set` command to specify your desired channel.
```package-install
npx hot-updater channel set
```
This command modifies the native project files for you. Here is what changes:
```tsx title="ios/HotUpdaterExample/Info.plist"
HOT_UPDATER_CHANNEL // [!code ++]
your_set_channel // [!code ++]
```
```xml title="android/app/src/main/AndroidManifest.xml"
```
For Expo, add the channel to the plugin configuration in your `app.json`
file.
```json title="app.json"
{
"expo": {
"plugins": [
[
"@hot-updater/react-native",
{
"channel": ""
}
]
]
}
}
```
Replace `` with your desired channel, for example
`production`.
After modifying `app.json`, run `prebuild` to apply the changes to the native
projects.
```package-install
npx expo prebuild --clean
```
## Custom Configuration Paths
For projects with non-standard structures or iOS app extensions, you can
configure custom paths for platform-specific configuration files in your
`hot-updater.config.ts`:
```typescript title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
// ... other configurations
platform: {
ios: {
infoPlistPaths: [
"ios/YourApp/Info.plist",
"ios/YourAppExtension/Info.plist", // Include extension Info.plist
"ios/NotificationService/Info.plist",
],
},
android: {
androidManifestPaths: [
"android/app/src/main/AndroidManifest.xml",
"android/app/src/debug/AndroidManifest.xml", // Include additional variant files
],
},
},
});
```
This is useful when:
- Your iOS project has app extensions such as widgets or notification services
- You have multiple Android build variants with different resource paths
- Your project does not follow the standard React Native file structure
`stringResourcePaths` is a deprecated read fallback for projects that still store Hot Updater values in `strings.xml`. New writes use application-level `AndroidManifest.xml` metadata.
**Important**: Configure these custom paths before running
`hot-updater channel set` so all relevant files are updated with the new
channel.
### 2. Rebuild the App with the New Channel
After setting the channel, rebuild your app in Release mode:
**iOS:**
```sh
cd ios && pod install && cd ..
npx react-native run-ios --mode Release
```
**Android:**
```sh
npx react-native run-android --mode Release
```
**iOS:**
```sh
npx rock run:ios --configuration Release
```
**Android:**
```sh
npx rock run:android --variant Release
```
**iOS:**
```sh
npx expo run:ios --configuration Release
```
**Android:**
```sh
npx expo run:android --variant release
```
### 3. Deploy Updates to That Channel
You can specify the target channel directly during deployment:
```package-install
npx hot-updater deploy -p <"ios" | "android"> -c ""
```
Replace `` with your target channel name, for example `dev`, `staging`,
or `production`.
## Check the Current Channel
Use `HotUpdater.getChannel()` to retrieve the app's effective channel in your UI.
This is useful for confirming that the build is using the intended default
channel.
### Example Usage
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { Text, View } from "react-native";
function App() {
const channel = HotUpdater.getChannel();
return (
Current Channel: {channel}
);
}
export default HotUpdater.wrap({
baseURL: "",
updateStrategy: "appVersion", // or "fingerprint"
})(App);
```
## Key Rules
- The default channel is embedded in the native app at build time.
- Changing that default channel requires a rebuild.
- `hot-updater deploy -c ` should match the channel you want the app to
receive updates from.
- `HotUpdater.getChannel()` returns the effective channel, which may differ at
runtime if a runtime channel switch is active.
- If you need temporary runtime switching, use
[Runtime Channel Switch](/docs/guides/runtime-channel-switch).
# Runtime Channel Switch (https://hot-updater.dev/docs/guides/runtime-channel-switch)
> Temporarily move a device to another channel at runtime, then return to the default channel when needed.
## Overview
Runtime channel switch lets a built app temporarily use a bundle from another
channel without changing the default channel embedded in the binary.
- The existing deployment process does not change.
- `HotUpdater.checkForUpdate({ channel })` checks another channel.
- The switch is persisted only after `updateInfo.updateBundle()` succeeds.
- You cannot jump directly from one switched runtime channel to another. Reset
back to the default channel first.
- `HotUpdater.resetChannel()` removes the switch and restores the original
bundle.
Set your app's default channel first. See
[Default Channel Setup](/docs/guides/channel-management). Runtime channel
switching is explicit. It only starts when you pass a
specific `channel` to `HotUpdater.checkForUpdate({ channel: "..." })`.
Calling `HotUpdater.checkForUpdate()` without `channel` keeps the existing
update flow for the app's current channel.
## Recommended Runtime Flow
Use this runtime channel switch flow when you want to opt a device into another
channel without rebuilding the native app:
1. Keep a build-time default channel such as `production`.
2. Check another channel with `HotUpdater.checkForUpdate({ channel: "beta" })`.
3. Call `updateInfo.updateBundle()` only when an update is returned.
4. Reload the app to start using the installed bundle.
5. Use `HotUpdater.getChannel()`, `HotUpdater.getDefaultChannel()`, and
`HotUpdater.isChannelSwitched()` to show the current state in your UI.
6. When you want to leave the runtime channel switch, call
`HotUpdater.resetChannel()` and reload again.
This keeps the full lifecycle explicit:
- Opt in with `checkForUpdate({ channel })` + `updateBundle()` + `reload()`
- Observe state with `getChannel()` + `getDefaultChannel()` + `isChannelSwitched()`
- Opt out with `resetChannel()` + `reload()`
## Opt Into Another Channel
```tsx
import { HotUpdater } from "@hot-updater/react-native";
async function enableBetaChannel() {
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
channel: "beta",
});
if (!updateInfo) {
console.log("No beta bundle available");
return false;
}
const installed = await updateInfo.updateBundle();
if (!installed) {
return false;
}
await HotUpdater.reload();
return true;
}
```
## Show Current State
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { Text, View } from "react-native";
function ChannelStatus() {
const currentChannel = HotUpdater.getChannel();
const defaultChannel = HotUpdater.getDefaultChannel();
const switched = HotUpdater.isChannelSwitched();
return (
Current channel: {currentChannel}Default channel: {defaultChannel}Runtime switch active: {switched ? "yes" : "no"}
);
}
```
## Reset to the Default Channel
```tsx
import { HotUpdater } from "@hot-updater/react-native";
async function restoreDefaultChannel() {
await HotUpdater.resetChannel();
await HotUpdater.reload();
}
```
If the app is already switched to a runtime channel such as `beta`, do not
try to jump directly to another runtime channel such as `alpha`.
Call `HotUpdater.resetChannel()` and reload first, then start a new
`checkForUpdate({ channel: "..." })` flow from the default channel.
## Important Behavior
- The existing deployment process is unchanged.
- `checkForUpdate({ channel: "beta" })` only checks the `beta` channel.
- `HotUpdater.checkForUpdate()` without a `channel` does not trigger runtime
switching.
- The app does not switch channels just by checking.
- If no update is returned, the app stays on the current channel.
- After `updateInfo.updateBundle()` succeeds and the app reloads,
`HotUpdater.getChannel()` returns the effective runtime channel.
- `HotUpdater.getDefaultChannel()` still returns the embedded default channel.
- If a runtime channel switch is already active, `checkForUpdate({ channel: "..." })`
cannot move directly to a different runtime channel. Call
`HotUpdater.resetChannel()` before starting another switch.
- If no runtime channel switch is active, `HotUpdater.resetChannel()` is a no-op.
Do not rely on `checkForUpdate({ channel: "" })` to return to
the default channel. That call only checks for an update. If there is nothing
new to install, the runtime channel switch remains active. Use
`HotUpdater.resetChannel()` when you want to fully leave the runtime channel
switch.
## Related APIs
- [`HotUpdater.checkForUpdate()`](/docs/react-native-api/checkForUpdate)
- [`HotUpdater.getChannel()`](/docs/react-native-api/getChannel)
- [`HotUpdater.getDefaultChannel()`](/docs/react-native-api/getDefaultChannel)
- [`HotUpdater.isChannelSwitched()`](/docs/react-native-api/isChannelSwitched)
- [`HotUpdater.resetChannel()`](/docs/react-native-api/resetChannel)
# Compression Strategy (https://hot-updater.dev/docs/guides/compression)
> Choose a compression format for your bundle distribution.
## Supported Formats
- **`zip`** - Standard ZIP format (DEFLATE algorithm). Fast compression and decompression.
- **`tar.gz`** - TAR archive with GZIP compression (LZ77 algorithm). ~10-15% smaller than ZIP.
- **`tar.br`** - TAR archive with [Brotli](https://github.com/google/brotli) compression. ~20-30% smaller than GZIP. Developed by Google for web compression.
## Configuration
Set `compressStrategy` in your `hot-updater.config.ts`:
```ts
import { defineConfig } from 'hot-updater';
export default defineConfig({
// ... other options
compressStrategy: 'tar.gz', // 'zip' | 'tar.gz' | 'tar.br'
});
```
## Usage
After setting the compression strategy, deploy your bundle:
```bash
npx hot-updater deploy -p ios
npx hot-updater deploy -p android
```
The bundle will be compressed and deployed using the specified format.
**How it works:**
- The client app automatically detects the compression format (ZIP, GZIP, or Brotli) and decompresses accordingly
- Users download the compressed bundle, reducing bandwidth usage
- Choose a format with better compression ratio to minimize download size and save users' data
Since the client handles all formats transparently, choose the format with the best compression ratio (`tar.br` or `tar.gz`) to reduce download sizes for your users.
# Doctor (https://hot-updater.dev/docs/guides/doctor)
> Check Hot Updater package versions, native setup, and server infrastructure.
## Overview
Use `hot-updater doctor` to check the parts that must agree for OTA updates to
work:
- All Hot Updater packages use compatible versions
- React Native native files are connected to Hot Updater
- Your deployed infrastructure server is not outdated
Run it after upgrading Hot Updater, or when OTA updates behave differently after
a package update.
```package-install
npx hot-updater doctor
```
In an interactive terminal, the command asks for your server base URL. Press
Enter to skip the server check.
For AI agents and other automation, use JSON output:
```package-install
npx hot-updater doctor --json
```
`--json` does not prompt for the server URL. Pass `--server-base-url` when you
want the infrastructure check included.
## Check Native Setup
When `@hot-updater/react-native` is installed and native iOS or Android
directories exist, `doctor` checks:
- iOS `AppDelegate` uses `HotUpdater.bundleURL()`
- Android `MainApplication` uses `HotUpdater.getJSBundleFile(...)`
- If `updateStrategy` is `fingerprint`, `fingerprint.json` exists and native
fingerprint hashes match it
- Signing settings match native public key entries
If any required native setting is missing, rebuild-time OTA configuration is not
healthy yet. Run the command shown by `doctor`, then rebuild the native app.
`doctor` does not require a default channel in native files. If
`HOT_UPDATER_CHANNEL` or `hot_updater_channel` exists, the command reports it as
context only.
For fingerprint projects, fix missing or stale native fingerprint settings with:
```package-install
npx hot-updater fingerprint create
```
## AI Agent Iteration
`doctor --json` returns structured issues that an agent can use without parsing
human-readable terminal output.
Each native issue includes:
- `code`: stable issue code, such as `MISSING_ANDROID_BUNDLE_PROVIDER`
- `platform`: `ios`, `android`, or `project`
- `paths`: related local files when available
- `fixability`: whether the issue is suitable for an agent loop
- `commands`: safe local commands when the fix is command-driven
Use `fixability` as the automation boundary:
| Fixability | Meaning |
| ---------- | -------------------------------------------------------------------------------------------------- |
| `auto` | The agent may inspect and edit local project files, then rerun doctor. |
| `command` | The agent may run the listed local command, then rerun doctor. |
| `blocked` | The issue needs credentials, environment variables, server access, or a human deployment decision. |
Native wiring, fingerprint creation, and native public key export/removal are
intended to be iterated locally by an agent. Infrastructure failures are marked
as blocked because applying migrations or redeploying a server usually depends
on provider credentials and environment-specific access.
Bundle index repair is only available when the active database adapter exposes
diagnostics hooks. Adapters without those hooks report `not-applicable`.
## Check Infrastructure
To check the deployed server in CI or a non-interactive shell, pass the public
update-check base URL.
```package-install
npx hot-updater doctor --server-base-url https://updates.example.com/api/check-update
```
`doctor` appends `/version` and checks:
```txt
https://updates.example.com/api/check-update/version
```
Example success output:
```txt
Checking the health of Hot Updater.
hot-updater CLI version: x.x.x
Server version endpoint: https://updates.example.com/api/check-update/version
Server version: x.x.x
Required infrastructure version: x.x.x
✅ Server infrastructure is up to date.
✅ All Hot Updater checks passed!
Doctor check complete.
```
## Update Package Versions
If `doctor` reports version mismatches, update every Hot Updater package in
`package.json` to the same compatible version, then run your package manager
install command.
## Update Outdated Infrastructure
If your server is outdated, `doctor` prints:
```txt
Infrastructure update required. Deploy server infrastructure version x.x.x or newer.
```
How to fix it depends on how you run Hot Updater:
- **Self-hosted server using `createHotUpdater`**: update all Hot Updater
packages together, including `@hot-updater/server`, then redeploy your server.
- **Managed providers (`aws`, `cloudflare`, `supabase`, `firebase`)**: run
`npx hot-updater init` again and redeploy the generated provider
infrastructure.
## Options
| Option | Description |
| ------------------------- | ------------------------------------------------------- |
| `--server-base-url ` | Check deployed infrastructure at `/version`. |
| `--json` | Print a machine-readable result for agents and scripts. |
# Bundle Signing (https://hot-updater.dev/docs/guides/bundle-signing)
> Sign OTA bundles to verify integrity and prevent tampering
## Why Bundle Signing?
Bundle signing prevents man-in-the-middle attacks, bundle tampering, and unauthorized deployments by using RSA-SHA256 signatures.
## Setup
```bash
# 1. Generate keys
npx hot-updater keys generate
# 2. Add to hot-updater.config.ts
# signing: { enabled: true, privateKeyPath: "./keys/private-key.pem" }
# 3. Export public key to native apps
npx hot-updater keys export-public
# 4. Rebuild and release native app
# 5. Deploy signed bundles
npx hot-updater deploy -p ios
```
You need to manually export the public key to native configuration files.
```bash
# 1. Generate keys
npx hot-updater keys generate
# 2. Add to hot-updater.config.ts
# signing: { enabled: true, privateKeyPath: "./keys/private-key.pem" }
# 3. Run prebuild (public key automatically embedded)
expo prebuild
# 4. Rebuild and release native app
# 5. Deploy signed bundles
npx hot-updater deploy -p ios
```
The Expo config plugin automatically extracts the public key from your private key during `expo prebuild`.
> **Important**: You must release a new app version with the public key before deploying signed bundles. Add `keys/` to `.gitignore`.
## Configuration
```ts title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
// ... other config
signing: {
enabled: true,
privateKeyPath: "./keys/private-key.pem",
},
});
```
## Commands
### Generate Keys
```bash
npx hot-updater keys generate [--output ./keys] [--key-size 4096]
```
Creates `private-key.pem` (keep secure) and `public-key.pem` in `./keys` directory.
### Export Public Key
```bash
npx hot-updater keys export-public [--print-only] [--yes]
```
Writes public key to:
- iOS: `Info.plist` → `HOT_UPDATER_PUBLIC_KEY`
- Android: application-level `AndroidManifest.xml` metadata → `com.hotupdater.PUBLIC_KEY`
The command auto-detects native files. For custom paths, configure `platform` in your config:
```ts title="hot-updater.config.ts"
export default defineConfig({
platform: {
android: {
androidManifestPaths: [
"android/app/src/main/AndroidManifest.xml",
"android/app/src/prod/AndroidManifest.xml", // production flavor
],
},
ios: {
infoPlistPaths: [
"ios/MyApp/Info.plist",
"ios/MyAppPro/Info.plist", // pro target
],
},
},
});
```
### Remove Public Keys
```bash
npx hot-updater keys remove [--yes]
```
## Manual Configuration
**iOS** (`Info.plist`):
```xml
HOT_UPDATER_PUBLIC_KEY-----BEGIN PUBLIC KEY-----\nMIIB...your-key...\n-----END PUBLIC KEY-----
```
**Android** (`AndroidManifest.xml`, inside ``):
```xml
```
The CLI can still read `hot_updater_public_key` from configured `stringResourcePaths` as a deprecated fallback for older projects.
## Expo Integration
Expo projects automatically embed the public key during `expo prebuild` when signing is enabled in `hot-updater.config.ts`.
### How It Works
The Expo config plugin (`@hot-updater/react-native`) reads your `hot-updater.config.ts`:
```ts title="hot-updater.config.ts"
export default defineConfig({
signing: {
enabled: true,
privateKeyPath: "./keys/private-key.pem",
},
// ... other config
});
```
When you run `expo prebuild`, the plugin:
1. Reads the signing config
2. Loads `./keys/public-key.pem` (derived from `privateKeyPath`)
3. Embeds it in native files automatically
**No need to run `npx hot-updater keys export-public` manually for Expo projects.**
### EAS Build
For EAS builds, the Expo plugin needs access to the private key to extract and embed the public key during prebuild. Store the private key as an environment variable:
#### Using EAS Secrets
```bash
# Store private key in EAS Secrets
eas env:create --name HOT_UPDATER_PRIVATE_KEY --value "$(cat keys/private-key.pem)"
```
The plugin automatically extracts the public key from `HOT_UPDATER_PRIVATE_KEY` during prebuild.
#### Using .easignore (Alternative)
For simpler setup, include the keys directory in EAS builds:
```txt title=".easignore"
!/keys
```
This tells EAS to include the `keys/` directory even though it's in `.gitignore`. The plugin will use the private key file directly during prebuild.
> **Note**: This approach is especially useful for local EAS builds (`eas build --local`) where you don't need to configure environment variables.
#### How It Works
During EAS build, the plugin checks for the public key in this order:
1. `HOT_UPDATER_PRIVATE_KEY` environment variable → Extract public key
2. Private key file at `privateKeyPath` → Extract public key
3. Public key file (derived from `privateKeyPath`) → Use directly
4. All sources failed → Build fails with error
## CI/CD Integration
### GitHub Actions
```yaml
- name: Setup signing key
run: |
mkdir -p keys
echo "${{ secrets.HOT_UPDATER_PRIVATE_KEY }}" > keys/private-key.pem
chmod 600 keys/private-key.pem
- name: Deploy
run: npx hot-updater deploy -p ios
```
### Other Platforms
Store keys in:
- GitHub Actions: Repository Secrets
- GitLab CI: CI/CD Variables (masked)
- AWS: Secrets Manager
- Azure: Key Vault
## Configuration States
| Config `signing.enabled` | Native Public Key | Result |
|--------------------------|-------------------|--------|
| `false` | Not present | ✅ Normal updates |
| `false` | Present | ❌ **Updates rejected** |
| `true` | Present | ✅ Verified updates |
| `true` | Not present | ❌ **Error: PublicKeyNotConfigured** |
> **Warning**: Config and native files must match. Mismatches cause update failures.
## Troubleshooting
### Updates Rejected
**Cause**: Public key in native files but `signing.enabled: false` in config.
**Fix**:
```bash
# Enable signing OR remove keys
npx hot-updater keys remove
```
### PublicKeyNotConfigured Error
**Cause**: `signing.enabled: true` but no public key in native files.
**Fix**:
```bash
npx hot-updater keys export-public
# Rebuild and release app
```
### Signature Verification Failed
**Causes**: Tampered bundle, wrong public key, or key mismatch.
**Fix**:
```bash
# Verify key matches
npx hot-updater keys export-public --print-only
```
## Key Rotation
1. Generate new key pair
2. Update `privateKeyPath` in config
3. Export new public key
4. Release new app version
5. Maintain compatibility until users update
# Native Build (alpha) (https://hot-updater.dev/docs/guides/native-build)
> Compile and run Android and iOS builds from the CLI.
## Overview
Hot Updater ships dedicated native helpers so you can create store-ready artifacts or boot the app on a device without leaving the CLI. `build:android` is available by default. `build:ios`, `run:android`, and `run:ios` are experimental and require `EXPERIMENTAL=1`. The `build:*` commands copy artifacts into a predictable output directory; `run:*` builds, installs, and launches directly without copying artifacts.
## Prerequisites
- React Native project with the platform directory you plan to build.
- `hot-updater.config.ts` defines at least one scheme under `nativeBuild.android` and/or `nativeBuild.ios`.
- Platform toolchains are installed locally (`gradlew`, `xcodebuild`, CocoaPods (or Bundler), `devicectl`/`simctl`).
- Run `hot-updater channel set ` so the channel exists in Info.plist or application-level AndroidManifest metadata.
- Decide on an update strategy (`appVersion` or `fingerprint`); the CLI follows it automatically.
## Configure nativeBuild schemes
Schemes describe how each platform should be built. Define as many as needed (debug APK, release AAB, AdHoc IPA, etc.) and reference them via `-s/--scheme`.
```ts title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
nativeBuild: {
android: {
releaseApk: {
packageName: "com.example.app",
variant: "Release",
aab: false,
},
internalAab: {
packageName: "com.example.app",
variant: "InternalRelease",
aab: true,
appModuleName: "app",
applicationId: "com.example.app.internal",
},
},
ios: {
release: {
bundleIdentifier: "com.example.app",
scheme: "ExampleApp",
configuration: "Release",
exportOptionsPlist: "./ios/ExampleApp/ExportOptions.plist",
installPods: true,
},
simulatorDebug: {
bundleIdentifier: "com.example.app.dev",
scheme: "ExampleApp",
configuration: "Debug",
platform: "ios",
installPods: true,
simulator: true,
},
},
},
// …
});
```
### Android scheme options
| Field | Description | Default |
| --- | --- | --- |
| `packageName` | Android application package name. | Required |
| `variant` | Android application module build variant. | `Release` |
| `aab` | Artifact type (`true` generates `.aab`, `false` generates `.apk`). | `true` |
| `appModuleName` | Android application module name. | `app` |
| `applicationId` | Android application ID. | same as `packageName` |
### iOS scheme options
| Field | Description | Default |
| --- | --- | --- |
| `bundleIdentifier` | The bundle identifier of the app. | Required |
| `platform` | Apple platform for build & archive. | `ios` |
| `scheme` | The Xcode scheme to build. | Required |
| `configuration` | The build configuration to use. | `Release` |
| `destination` | The destination for the build. | `['generic/platform=iOS']` |
| `exportOptionsPlist` | Path to a plist file that specifies options for exporting the archive. | `undefined` |
| `exportExtraParams` | Additional parameters for `exportArchive`. | `[]` |
| `xcconfig` | Path to an `.xcconfig` file to include additional build settings. | `undefined` |
| `installPods` | Automatically install CocoaPods dependencies before building. | `false` |
| `simulator` | Build for an iOS simulator; do not combine with `destination`. | `false` |
| `extraParams` | Additional parameters passed to `xcodebuild`. | `[]` |
## CLI commands
All commands require `-s/--scheme` unless `-i/--interactive` is used. Artifact output applies only to `build:*`.
```
Options:
-s, --scheme predefined scheme for the native build configuration
-o, --output-path where build:* artifacts will be copied (default: .hot-updater/output/build//)
-i, --interactive interactive mode (default: false)
-h, --help display help for command
```
### `hot-updater build:android`
Assembles the selected Gradle variant and copies the resulting APK/AAB to the output directory.
```package-install
npx hot-updater build:android -s releaseApk
```
- Generates `.apk` or `.aab` by option.
### `hot-updater build:ios`
This experimental command archives (and optionally exports) the selected scheme using `xcodebuild`, then copies the `.xcarchive`, `.app`, or `.ipa`.
```package-install
EXPERIMENTAL=1 npx hot-updater build:ios -s release
```
- If `exportOptionsPlist` is present, an IPA export is performed; otherwise the `.xcarchive` and extracted `.app` are stored.
### `hot-updater run:android`
This experimental command builds an APK, installs it on target devices, and launches the main activity.
```
Options:
-d, --device [deviceName | deviceId] specify the ADB device name or use default
--port specify the port number
--app-id-suffix specify the app ID suffix
```
```package-install
EXPERIMENTAL=1 npx hot-updater run:android -s debugApk -d "Pixel_6_Pro_API_35" --port 8082
```
- `-d` selects a specific device; otherwise all connected devices receive the build (or the CLI launches the first emulator).
- `--port` forwards the Metro port before the app starts.
### `hot-updater run:ios`
This experimental command builds for simulator or device, installs the app, and launches it.
```
Options:
-d, --device [deviceName | deviceId] specify an Apple device/simulator name or identifier
```
```package-install
EXPERIMENTAL=1 npx hot-updater run:ios -s simulatorDebug -d "iPhone 15 (iOS 17.5)"
```
- Works with `devicectl` (physical devices) and `simctl` (simulators); interactive mode lists everything discovered.
- If no device is specified, the first available simulator is used and Simulator.app is opened automatically.
## Artifact storage
For `build:*`, artifacts default to `.hot-updater/output/build//`. The directory is recreated on every build, so copy artifacts elsewhere if you need to keep older output. Copying happens after build plugin hooks complete. The `run:*` commands do not run those hooks or copy artifacts.
## Fingerprint and version awareness
- `updateStrategy: "fingerprint"` regenerates `fingerprint.json` before the build and surfaces diffs from the last checked-in fingerprint.
- `updateStrategy: "appVersion"` reads the native app version (`CFBundleShortVersionString` / `versionName`). Missing values stop the build so artifacts never ship with unknown versions.
# App Version Update Strategy (https://hot-updater.dev/docs/guides/update-strategies/app-version)
> Manually target specific app versions for OTA updates instead of using automatic compatibility checks.
## Overview
The App Version strategy gives you manual control over which app versions receive updates. You specify exact versions or ranges when deploying, rather than relying on automatic fingerprint detection.
**When to use it**: Choose this if you prefer explicit version targeting over automated compatibility checks.
## Setup
Configure the strategy in your Hot Updater config:
```typescript title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
updateStrategy: "appVersion",
});
```
## Version Targeting
Use version ranges to control which app versions receive updates. The `-t` option accepts various expressions:
| Range | Who gets the update |
| :--- | :--- |
| `1.2.3` | Only version `1.2.3` |
| `*` | All versions |
| `1.2.x` | Any patch version of `1.2` |
| `1.2.3 - 1.2.7` | Versions `1.2.3` through `1.2.7` (inclusive) |
| `>=1.2.3 <1.2.7` | Versions `1.2.3` (inclusive) to `1.2.7` (exclusive) |
| `1.2` | Same as `>=1.2.0 <1.3.0` |
| `~1.2.3` | Same as `>=1.2.3 <1.3.0` |
| `^1.2.3` | Same as `>=1.2.3 <2.0.0` |
## Deployment
Specify the target version when deploying:
```package-install
npx hot-updater deploy -p <"ios" | "android"> -t "1.x.x"
```
Examples:
- `npx hot-updater deploy -p ios -t "1.0.0"` - Only version 1.0.0
- `npx hot-updater deploy -p android -t ">=1.2.0"` - Version 1.2.0 and above
- `npx hot-updater deploy -p ios -t "*"` - All versions
## Client Setup
Configure your React Native app:
```tsx title="App.tsx"
import { HotUpdater } from "@hot-updater/react-native";
import { View, Text } from "react-native";
function App() {
return (
Hello World
);
}
export default HotUpdater.wrap({
baseURL: "https://your-update-server.com/api/update-check", // [!code ++]
updateStrategy: "appVersion", // [!code ++]
})(App);
```
The client automatically constructs this endpoint:
```
GET {baseUrl}/app-version/:platform/:appVersion/:channel/:minBundleId/:bundleId
```
## Testing the Endpoint
Test your update endpoint using curl:
```bash
curl "https://your-update-endpoint.com/check-update/app-version/ios/1.0.0/production/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000001"
```
Parameters:
- `:platform` - `ios` or `android`
- `:appVersion` - Current app version (e.g., `1.0.0`)
- `:channel` - Channel name (e.g., `production`, `staging`)
- `:minBundleId` - Minimum supported bundle ID
- `:bundleId` - Current bundle ID
# Fingerprint Update Strategy (https://hot-updater.dev/docs/guides/update-strategies/fingerprint)
> Automatically prevent incompatible OTA updates by tracking native code changes with Expo's fingerprint library.
## Why Choose Fingerprint?
Fingerprint automatically detects native code changes and blocks incompatible OTA updates. This ensures only safe updates reach your users.
**Fingerprint vs App Version:**
- **Fingerprint**: Automatic protection - detects native changes and blocks unsafe updates
- **App Version**: Manual control - you specify version targets, no automatic checking
Choose Fingerprint for automatic safety. Choose App Version for manual control.
## Setup
`appVersion` is the default update strategy. Fingerprint targeting is opt-in, so configure it explicitly:
```typescript title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
updateStrategy: "fingerprint",
});
```
### Include Additional Files (Optional)
Track extra files that affect native compatibility:
```typescript title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
updateStrategy: "fingerprint",
fingerprint: {
extraSources: [
"config/native-config.json",
"scripts/post-build.sh",
],
debug: true,
},
});
```
An array is shared: every entry is hashed into both the iOS and the Android
fingerprint. When the native inputs differ per platform, use the object form so
that an iOS-only change does not move the Android fingerprint (and vice versa):
```typescript title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
updateStrategy: "fingerprint",
fingerprint: {
extraSources: {
ios: ["ios/.env"],
android: ["android/local.properties"],
},
},
});
```
## Workflow
### Before App Store Submission
**Step 1: Generate Fingerprint**
Before building for App Store, generate the fingerprint:
```package-install
npx hot-updater fingerprint create
```
This creates a `fingerprint.json` file and embeds the hash in your native files:
- iOS: `ios/YourApp/Info.plist`
- Android: application-level `AndroidManifest.xml` metadata named `com.hotupdater.FINGERPRINT_HASH`
Example `fingerprint.json`:
```json
{
"ios": {
"hash": "11142b9062165fa48665f5efa095dd94e9e45eb0"
},
"android": {
"hash": "c763ed5729a0bcccf23248ee0183ddf9016c2e6e"
}
}
```
**Step 2: Build and Submit**
Build your app with the embedded fingerprint and submit to the App Store.
**Step 3: Deploy OTA Updates**
After your app is live, deploy JavaScript-only updates:
```package-install
npx hot-updater deploy
```
The system automatically ensures only compatible updates reach users.
### When Native Code Changes
Check if your fingerprint needs updating:
```package-install
npx hot-updater fingerprint
```
If there's a mismatch, create a new fingerprint:
```package-install
npx hot-updater fingerprint create
```
**Important**: After creating a new fingerprint, you must rebuild your app. The new fingerprint must be embedded in the app binary before deploying OTA updates.
## Client Setup
Configure your React Native app:
```tsx title="App.tsx"
import { HotUpdater } from "@hot-updater/react-native";
import { View, Text } from "react-native";
function App() {
return (
Hello World
);
}
export default HotUpdater.wrap({
baseURL: "https://your-update-server.com/api/update-check", // [!code ++]
updateStrategy: "fingerprint", // [!code ++]
})(App);
```
The client automatically constructs this endpoint:
```
GET {baseUrl}/fingerprint/:platform/:fingerprintHash/:channel/:minBundleId/:bundleId
```
## How It Works
### JavaScript/UI Changes ✅ OTA Update Safe
```javascript
// ✅ Safe for OTA updates
// - Component logic changes
// - Style and layout updates
// - New screens
// - Business logic changes
// - API call modifications
```
**Result**: Fingerprint unchanged → OTA update deployed
### Native Code Changes ⚠️ Rebuild Required
```bash
# ⚠️ Requires native rebuild
# - New native modules (react-native-camera)
# - React Native version updates
# - Native iOS/Android code changes
# - Build configuration changes
```
**Result**: Fingerprint changed → OTA blocked → Rebuild needed
If you try to deploy with a changed fingerprint:
```bash
$ npx hot-updater deploy
❌ Fingerprint mismatch!
💡 Native code changed. You need to:
1. Run: npx hot-updater fingerprint create
2. Rebuild and resubmit your app
3. Then deploy OTA updates
```
## Advanced
### Multiple App Targets
`fingerprint create` automatically handles standard React Native projects. Only configure custom paths if you have:
- iOS app extensions (widgets, share extensions)
- Multiple Android build variants
- Non-standard project structure
```typescript title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
updateStrategy: "fingerprint",
platform: {
ios: {
infoPlistPaths: [
"ios/YourApp/Info.plist",
"ios/YourAppWidget/Info.plist",
"ios/YourAppExtension/Info.plist"
]
},
android: {
androidManifestPaths: [
"android/app/src/main/AndroidManifest.xml",
"android/app/src/debug/AndroidManifest.xml"
]
}
}
});
```
💡 Most projects don't need this - the defaults work perfectly.
`stringResourcePaths` remains a deprecated read fallback for older projects.
### Testing the Endpoint
Test your update endpoint with curl:
```bash
curl "https://your-update-endpoint.com/check-update/fingerprint/ios/11142b9062165fa48665f5efa095dd94e9e45eb0/production/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000001"
```
Parameters:
- `:platform` - `ios` or `android`
- `:fingerprintHash` - Current fingerprint hash
- `:channel` - Channel name (e.g., `production`, `staging`)
- `:minBundleId` - Minimum supported bundle ID
- `:bundleId` - Current bundle ID
# wrap (https://hot-updater.dev/docs/react-native-api/wrap)
> `HotUpdater.wrap` stages standard updates for the next app start and reloads force updates by default.
## Usage
> **Important:** Configure Hot Updater with either `HotUpdater.wrap` or
> [`HotUpdater.init`](/docs/react-native-api/init) before calling update APIs.
> This enables automatic crash detection and rollback. Update methods will
> throw an error if neither API is used.
`HotUpdater.wrap` configures automatic updates. The automatic mode is the
default, so `updateMode` is no longer needed.
A standard update is prepared and staged without reloading the React Native
runtime currently in use. Once staging finishes successfully, it becomes active
the next time that runtime starts, normally on the next cold app launch. In the
automatic `HotUpdater.wrap` flow, responses with `shouldForceUpdate: true`,
including bundle-changing server-directed rollbacks, prepare the selected
transition and then reload by default. Set `reloadOnForceUpdate: false` when the
current session must remain uninterrupted.
### Automatic Updates
Use this for apps that want automatic OTA updates. This is the standard approach with full update management.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { View, Text } from "react-native";
function App() {
return (
Hello World
);
}
export default HotUpdater.wrap({ // [!code hl:8]
baseURL: "",
updateStrategy: "appVersion", // or "fingerprint"
// If you need to send request headers, you can use the `requestHeaders` option.
requestHeaders: {
"Authorization": "Bearer ",
},
})(App);
```
### Manual Updates
Use [`HotUpdater.init`](/docs/react-native-api/init) for manual update flows.
Initialize once with `HotUpdater.init`, export your root component directly,
then call `checkForUpdate` or `updateBundle` when needed.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
HotUpdater.init({
baseURL: "",
});
```
Then use `checkForUpdate` or `updateBundle` manually when needed:
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { useEffect } from "react";
function App() {
useEffect(() => {
const checkUpdate = async () => {
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion", // Required: specify update strategy
requestHeaders: {
Authorization: "Bearer ",
},
});
if (!updateInfo) {
console.log("No update found");
return;
}
await updateInfo.updateBundle();
if (updateInfo.shouldForceUpdate) {
await HotUpdater.reload();
}
};
checkUpdate();
}, []);
// ... your app
}
HotUpdater.init({
baseURL: "",
requestHeaders: {
"Authorization": "Bearer ",
},
});
export default App;
```
## Configuration Reference
`HotUpdater.wrap` accepts automatic update options.
### Common Options
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `baseURL` | `string \| () => string \| Promise` | Yes* | Your update server URL (standard approach) |
| `resolver` | `HotUpdaterResolver` | Yes* | Custom network operations (advanced) |
| `requestHeaders` | `Record` | No | Custom HTTP headers for update requests |
| `requestTimeout` | `number` | No | Request timeout in milliseconds (default: 5000) |
| `onNotifyAppReady` | `(result) => void` | No | Callback invoked after native app-ready state is read |
\*Either `baseURL` or `resolver` must be provided (mutually exclusive)
### Automatic Mode Options
The following options are available in automatic mode:
| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `updateStrategy` | `"appVersion" \| "fingerprint"` | Yes | Update detection strategy |
| `requestHeaders` | `Record` | No | Custom HTTP headers for update requests |
| `requestTimeout` | `number` | No | Request timeout in milliseconds (default: 5000) |
| `fallbackComponent` | `React.FC` | No | UI component shown during updates |
| `onProgress` | `(progress: number) => void` | No | Callback fired during bundle download (0-1) |
| `reloadOnForceUpdate` | `boolean` | No | Auto-reload on force updates (default: true) |
| `onUpdateProcessCompleted` | `(response) => void` | No | Callback when update process completes |
| `onError` | `(error) => void` | No | Error handler for update failures |
#### `fallbackComponent`
During an update check, access to the entry point is temporarily blocked while communicating with the server.
- If the update is **force update**, the entry point remains blocked, and the progress updates as the bundle downloads.
- If **not force update**, the entry point is only blocked during the update check.
Without a `fallbackComponent`, the bundle downloads without blocking the screen.
**Props:**
- `progress`: Download progress (0-1, e.g., for a progress bar)
- `status`: Update state (`CHECK_FOR_UPDATE` or `UPDATING`)
- `message`: Optional server message (`string | null`)
**Example:**
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { View, Text, Modal } from "react-native";
function App() {
return (
Hello World
);
}
export default HotUpdater.wrap({ // [!code hl:32]
baseURL: "",
updateStrategy: "appVersion", // or "fingerprint"
fallbackComponent: ({ progress, status, message }) => (
{/* You can put a splash image here. */}
{status === "UPDATING" ? "Updating..." : "Checking for Update..."}
{message && (
{message}
)}
{progress > 0 ? (
{Math.round(progress * 100)}%
) : null}
),
})(App);
```
#### `reloadOnForceUpdate`
When the automatic `HotUpdater.wrap` flow receives an update with
`shouldForceUpdate: true`, it prepares the selected transition and reloads the
app by default. Bundle-changing server-directed rollbacks also use this path.
If set to `false`, the current React Native runtime keeps running and the staged
update becomes active on the next runtime start or after a later explicit
`HotUpdater.reload()` call.
This option only controls the automatic `HotUpdater.wrap` flow.
`updateBundle()` never reloads the app by itself.
The actual reload behavior follows [`HotUpdater.setReloadBehavior()`](/docs/react-native-api/setReloadBehavior).
**Example with auto-reload:**
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { View, Text } from "react-native";
function App() {
return (
Hello World
);
}
export default HotUpdater.wrap({
baseURL: "",
updateStrategy: "appVersion", // or "fingerprint"
// If you need to send request headers, you can use the `requestHeaders` option.
requestHeaders: {
"Authorization": "Bearer ",
},
reloadOnForceUpdate: true, // Automatically reload the app on force updates // [!code hl]
})(App);
```
**Example without auto-reload:**
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { View, Text } from "react-native";
function App() {
return (
Hello World
);
}
export default HotUpdater.wrap({
baseURL: "",
updateStrategy: "appVersion", // or "fingerprint"
// If you need to send request headers, you can use the `requestHeaders` option.
requestHeaders: {
"Authorization": "Bearer ",
},
reloadOnForceUpdate: false, // Keep the current session running // [!code hl]
})(App);
```
#### `onUpdateProcessCompleted`
Reports when automatic update handling has finished from the wrapper's
perspective.
For a non-force update, the automatic flow invokes this callback after starting
the non-blocking download, not after the download finishes. Do not use it as a
download-readiness signal.
**Callback Arguments:**
| Property | Type | Description |
|----------|-------------|-------------|
| `status` | "ROLLBACK" \| "UPDATE" \| "UP_TO_DATE" | The status of the update process |
| `shouldForceUpdate` | boolean | Whether the update process is forced |
| `id` | string | The ID of the bundle to update |
| `message` | `string \| null` | The optional message of the update process |
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { View, Text } from "react-native";
function App() {
return (
Hello World
);
}
export default HotUpdater.wrap({
baseURL: "",
updateStrategy: "appVersion", // or "fingerprint"
// If you need to send request headers, you can use the `requestHeaders` option.
requestHeaders: {
"Authorization": "Bearer ",
},
onUpdateProcessCompleted: ({ status, shouldForceUpdate, id, message }) => {
console.log("Bundle updated:", status, shouldForceUpdate, id, message);
},
// If you need to show the progress while downloading the new bundle, you can use the `onProgress` option.
onProgress: (progress) => {
console.log("Bundle downloading progress:", progress);
},
})(App);
```
#### `onError`
Handles all errors during the update process.
**Example:**
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { Alert } from "react-native";
export default HotUpdater.wrap({
baseURL: "",
updateStrategy: "appVersion",
onError: (error) => { // [!code hl:5]
// Handle other errors
console.error("Update error:", error);
},
})(App);
```
## How It Works
When you use `HotUpdater.wrap` with automatic updates, it constructs the appropriate endpoint URL based on the `updateStrategy`:
* For `updateStrategy: "appVersion"`: `GET {baseURL}/app-version/:platform/:appVersion/:channel/:minBundleId/:bundleId`
* For `updateStrategy: "fingerprint"`: `GET {baseURL}/fingerprint/:platform/:fingerprintHash/:channel/:minBundleId/:bundleId`
The function automatically appends the correct path and parameters to your `baseURL`.
## Advanced: Custom Resolver
For advanced use cases where you need full control over network operations - such as implementing a custom server, using GraphQL, or complex authentication flows - you can use a custom `resolver` instead of `baseURL`.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { useEffect } from "react";
import YourApp from "./YourApp";
function App() {
useEffect(() => {
const checkUpdate = async () => {
// When you call HotUpdater.checkForUpdate(),
// it will use the resolver.checkUpdate() defined below
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
});
if (updateInfo) {
await updateInfo.updateBundle();
if (updateInfo.shouldForceUpdate) {
await HotUpdater.reload();
}
}
};
checkUpdate();
}, []);
return ;
}
export default HotUpdater.wrap({
resolver: { // [!code ++]
// Override the default update check logic // [!code ++]
checkUpdate: async (params) => { // [!code ++]
// Custom network logic - GraphQL, custom API, etc. // [!code ++]
const response = await fetch(`https://custom-api.com/check`, { // [!code ++]
method: 'POST', // [!code ++]
body: JSON.stringify({ // [!code ++]
platform: params.platform, // [!code ++]
appVersion: params.appVersion, // [!code ++]
bundleId: params.bundleId, // [!code ++]
}), // [!code ++]
headers: params.requestHeaders, // [!code ++]
}); // [!code ++]
if (!response.ok) return null; // [!code ++]
return response.json(); // [!code ++]
}, // [!code ++]
}, // [!code ++]
updateStrategy: "appVersion",
})(App);
```
> **Note**: The `resolver` option is mutually exclusive with `baseURL`. Using `resolver.checkUpdate()` overrides the default update check implementation.
## Flag Behavior
| Update Response | Runtime Behavior | How to Enable |
|----------------------------------|-----------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `shouldForceUpdate: false` | Stages the selected bundle without reloading the current runtime; it becomes active on the next runtime start. | Default setting |
| `shouldForceUpdate: true` | `HotUpdater.wrap` reloads after preparing the selected transition; `reloadOnForceUpdate: false` defers it to a later start. | Use `--force-update` or the console; bundle-changing rollbacks also return it. |
# init (https://hot-updater.dev/docs/react-native-api/init)
> `HotUpdater.init` initializes HotUpdater for manual update flows without wrapping a React component.
## Usage
Use `HotUpdater.init` when you want a fully custom update flow and cannot, or do
not want to, wrap your root component with `HotUpdater.wrap`. Call it once when
your runtime considers the app ready. This API exists for apps that only need
Hot Updater initialization without a React HOC.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
HotUpdater.init({
baseURL: "",
requestHeaders: {
Authorization: "Bearer ",
},
onError: error => {
console.error("Hot Updater failed", error);
},
});
```
`baseURL` can also be resolved at runtime. The function may return a string or
a promise, and Hot Updater calls it before each update check.
```tsx
HotUpdater.init({
baseURL: async () => {
return await getUpdateServerURL();
},
});
```
After initialization, call `HotUpdater.checkForUpdate()` wherever your runtime
or app state says it is safe to check.
```tsx
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
});
if (!updateInfo) {
return;
}
await updateInfo.updateBundle();
if (updateInfo.shouldForceUpdate) {
await HotUpdater.reload();
}
```
## Configuration Reference
| Option | Type | Required | Description |
| ------------------ | ------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `baseURL` | `string \| () => string \| Promise` | Yes* | Your update server URL or runtime URL resolver |
| `resolver` | `HotUpdaterResolver` | Yes* | Custom network operations |
| `requestHeaders` | `Record` | No | Shared headers used by update checks and app-ready notifications |
| `requestTimeout` | `number` | No | Request timeout in milliseconds (default: 5000) |
| `onNotifyAppReady` | `(result) => void` | No | Callback invoked after native app-ready state is read |
| `onError` | `(error) => void` | No | Default error handler for initialization and update checks |
\*Either `baseURL` or `resolver` must be provided (mutually exclusive).
`HotUpdater.checkForUpdate({ onError })` overrides the `onError` handler from
`HotUpdater.init` for that specific update check.
## When to Use init
Use `HotUpdater.init` when another runtime owns the root component, when you
need to initialize before rendering, or when your app has a custom shell that
does not make a root HOC convenient.
Use `HotUpdater.wrap` when you want Hot Updater to manage the root component
lifecycle directly, especially for automatic update checks with a fallback UI.
## Related
- [`HotUpdater.wrap()`](/docs/react-native-api/wrap)
- [`HotUpdater.checkForUpdate()`](/docs/react-native-api/checkForUpdate)
- [Custom Update](/docs/guides/custom-update)
# checkForUpdate (https://hot-updater.dev/docs/react-native-api/checkForUpdate)
> The `checkForUpdate` function checks if there is an available update for the app by comparing the current app version and platform with the update server's bundle information.
## Usage
Use `checkForUpdate` to verify if an update bundle is available. The function
reuses the update source configured in `HotUpdater.wrap()` or
`HotUpdater.init()`.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
// First, configure baseURL with init
HotUpdater.init({
baseURL: "",
});
// Use checkForUpdate - it reuses the configured baseURL
async function checkForAppUpdate() {
try {
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
requestHeaders: {
Authorization: "Bearer ",
},
});
if (!updateInfo) {
return {
status: "UP_TO_DATE",
};
}
/**
* You can apply updates using one of two methods:
*
* Method 1: Use the updateBundle() method from the updateInfo object
* - A convenience method built into the return value from checkForUpdate
* - Performs the same function as HotUpdater.updateBundle with all required arguments pre-filled
*/
await updateInfo.updateBundle();
/**
* Method 2: Call HotUpdater.updateBundle() directly
* - Explicitly pass the necessary values extracted from updateInfo
*/
// await HotUpdater.updateBundle({
// bundleId: updateInfo.id,
// fileUrl: updateInfo.fileUrl,
// fileHash: updateInfo.fileHash,
// status: updateInfo.status,
// });
if (updateInfo.shouldForceUpdate) {
await HotUpdater.reload();
}
return updateInfo;
} catch (error) {
console.error("Failed to check for update:", error);
return null;
}
}
```
## Important: HotUpdater.wrap or HotUpdater.init Required
When using `checkForUpdate`, configure Hot Updater first with
`HotUpdater.wrap()` or `HotUpdater.init()`. This is required for proper crash
detection and rollback functionality.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { useEffect } from "react";
import YourApp from "./YourApp";
function App() {
useEffect(() => {
HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
requestHeaders: {
Authorization: "Bearer ",
},
}).then(async (updateInfo) => {
if (updateInfo) {
await updateInfo.updateBundle();
if (updateInfo.shouldForceUpdate) {
await HotUpdater.reload();
}
}
}).catch((error) => {
console.error("Failed to check for update:", error);
});
}, []);
return ;
}
HotUpdater.init({
baseURL: "",
});
export default App;
```
`HotUpdater.init()` configures Hot Updater without the unnecessary HOC that
manual `wrap` would create:
```tsx
HotUpdater.init({
baseURL: "",
});
```
Without `wrap` or `init`, calling `checkForUpdate` will throw an error with
instructions on how to fix it.
## Parameters
The `checkForUpdate` function accepts the following parameters:
| Parameter | Type | Required | Description |
|-------------------|--------------------------------|----------|----------------------------------------------------------------------------------|
| `updateStrategy` | `"appVersion"` \| `"fingerprint"` | ✅ | Update detection strategy for this check. |
| `channel` | `string` | ❌ | Channel to check. The switch is persisted only after the returned update is applied. |
| `requestHeaders` | `Record` | ❌ | Optional headers to include in the update request. |
| `requestTimeout` | `number` | ❌ | Request timeout in milliseconds (default: 5000). |
| `onError` | `(error: Error) => void` | ❌ | Error callback. |
The update source is always the `baseURL` or `resolver` configured by
`HotUpdater.wrap()` or `HotUpdater.init()`; it cannot be overridden in
`checkForUpdate`.
## How It Works
When you call `checkForUpdate`, the function uses the configured `baseURL` and
the provided `updateStrategy` to construct the appropriate endpoint URL:
* For `updateStrategy: "appVersion"`: `GET {baseURL}/app-version/:platform/:appVersion/:channel/:minBundleId/:bundleId/:cohort`
* For `updateStrategy: "fingerprint"`: `GET {baseURL}/fingerprint/:platform/:fingerprintHash/:channel/:minBundleId/:bundleId/:cohort`
For example, if you configured `baseURL: "https://your-update-server.com/api/update-check"` in `wrap`, the function automatically appends the correct path and parameters.
## Return Value
The function returns an update object or `null` if the app is up to date.
| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Bundle identifier. |
| `shouldForceUpdate` | `boolean` | Whether the app should reload immediately after download. |
| `fileUrl` | `string \| null` | Bundle archive URL, or `null` for a rollback without an archive. |
| `fileHash` | `string \| null` | Bundle hash or signature used by native verification. |
| `message` | `string \| null` | Optional update message. |
| `status` | `"ROLLBACK" \| "UPDATE"` | Update operation. |
| `updateBundle` | `() => Promise` | Applies this result with the required values pre-filled. |
Prefer the returned `updateBundle()` helper so the values from that update
check are applied together.
### Example Return Value
The JSON response provides the data fields; the client adds the callable
`updateBundle()` helper.
```json
{
"id": "01952bbd-e7b2-7931-aee8-2e2187caa0ce",
"shouldForceUpdate": true,
"status": "UPDATE",
"fileUrl": "https://example.com/bundles/update.bundle",
"fileHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"message": "This is a test message"
}
```
# updateBundle (https://hot-updater.dev/docs/react-native-api/updateBundle)
> Stage an update transition for the next React Native runtime without reloading the current one.
## Usage
Use `updateBundle` to stage an available update transition, downloading and
verifying a bundle when needed. Use the transition information returned by
`checkForUpdate`. The function does not reload the React Native runtime
currently in use.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
async function stageAppUpdate() {
try {
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion", // or "fingerprint"
requestHeaders: {
Authorization: "Bearer ",
},
});
if (!updateInfo) {
return {
status: "UP_TO_DATE",
};
}
/**
* You can stage updates using one of two methods:
*
* Method 1: (RECOMMENDED) Use the updateBundle() method from the updateInfo object
* - A convenience method built into the return value from checkForUpdate
* - Automatically includes fileHash for secure verification
* - All required arguments are pre-filled from the checkForUpdate response
*/
const didUpdate = await updateInfo.updateBundle();
/**
* Method 2: Call HotUpdater.updateBundle() directly
* - Explicitly pass the necessary values extracted from updateInfo
* - You must manually include fileHash for security
*/
// const didUpdate = await HotUpdater.updateBundle({
// bundleId: updateInfo.id,
// fileUrl: updateInfo.fileUrl,
// fileHash: updateInfo.fileHash,
// status: updateInfo.status,
// });
if (!didUpdate) {
console.warn("Update transition was not staged");
return;
}
console.log("Bundle transition staged successfully");
if (updateInfo.shouldForceUpdate) {
await HotUpdater.reload();
}
} catch (error) {
console.error("Failed to stage update:", error);
}
}
```
## Parameters
The object form of `HotUpdater.updateBundle()` accepts the following required parameters:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `bundleId` | `string` | ✅ | Unique identifier of the update bundle. |
| `fileUrl` | `string \| null` | ✅ | Bundle archive URL, or `null` for a rollback without an archive. |
| `fileHash` | `string \| null` | ✅ | SHA-256 hash or `sig:` verification value; `null` when verification is not provided. |
| `status` | `"ROLLBACK" \| "UPDATE"` | ✅ | Operation represented by the update. |
### Behavior
- Downloads the specified bundle when `fileUrl` is not `null`.
- If `fileHash` contains a SHA-256 hash, verifies the downloaded file before extraction.
- If `fileHash` starts with `sig:`, verifies the bundle signature.
- If `fileHash` is `null`, proceeds without archive verification.
- Stages the selected bundle for the next React Native runtime start without
replacing the code already running.
- Never reloads the app by itself. Call `HotUpdater.reload()` explicitly to
start the staged bundle immediately; the automatic `HotUpdater.wrap` flow
handles force updates separately.
- An in-progress download is not guaranteed to finish after the app is
force-quit.
### Security Recommendation
**Always preserve a non-null `fileHash` returned by `checkForUpdate()`.** Native verification rejects corrupted archives and bundles that fail signature verification.
#### Recommended Approach
**Use `updateInfo.updateBundle()` instead of `HotUpdater.updateBundle()`** whenever possible. It passes the required values from the corresponding update check automatically.
```tsx
// Recommended: required values are automatically included.
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
});
if (updateInfo) {
await updateInfo.updateBundle();
}
```
# reload (https://hot-updater.dev/docs/react-native-api/reload)
> Apply a downloaded bundle immediately.
## Usage
`HotUpdater.reload()` applies the currently downloaded bundle immediately.
- If no new bundle is ready, it reloads the current app code
- If a bundle was downloaded, that bundle becomes active immediately
- The exact behavior depends on [`HotUpdater.setReloadBehavior()`](./setReloadBehavior)
```tsx
import { HotUpdater } from "@hot-updater/react-native";
async function syncUpdate() {
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
});
if (!updateInfo) return;
await updateInfo.updateBundle();
if (updateInfo.shouldForceUpdate) {
await HotUpdater.reload(); // [!code hl]
}
}
```
This is the most common manual usage pattern:
## Reload behavior
By default, `HotUpdater.reload()` uses `processRestart`.
- Android: cold process restart
- iOS: behaves like normal React Native reload
Use [`HotUpdater.setReloadBehavior("reload")`](./setReloadBehavior) only if you explicitly want the old in-process React Native reload path.
## Related APIs
- [`HotUpdater.setReloadBehavior()`](/docs/react-native-api/setReloadBehavior)
- [`HotUpdater.checkForUpdate()`](/docs/react-native-api/checkForUpdate)
- [`HotUpdater.isUpdateDownloaded()`](/docs/react-native-api/isUpdateDownloaded)
- [`HotUpdater.wrap()`](/docs/react-native-api/wrap)
# setReloadBehavior (https://hot-updater.dev/docs/react-native-api/setReloadBehavior)
> Control how HotUpdater.reload() is executed.
## Usage
Use `HotUpdater.setReloadBehavior()` to control how [`HotUpdater.reload()`](./reload) is applied.
The default is `processRestart`.
This is a global setting, so calling it once during app startup is enough.
- `reload` and `processRestart` are Android-focused built-in behaviors
- On iOS, both built-in behaviors behave like the normal React Native reload flow
- `custom` works on both Android and iOS
```tsx
import { HotUpdater } from "@hot-updater/react-native";
HotUpdater.setReloadBehavior("processRestart");
```
## Why this exists
Android's normal React Native reload is an in-process reload.
The current React instance goes down, a new one comes up, and native modules can still touch JS in the middle of that handoff.
We reproduced a real Android release failure pattern where a third-party native module or background callback kept emitting to JS while React was being recreated.
That can show up as errors like `ReactNoCrashSoftException`, `reactInstance is null`, or `Tried to access a JS module before the React instance was fully set up.`
Depending on timing, the result can be a soft exception, blank screen, or full app crash.
`processRestart` avoids that class of problem by restarting the app cold instead of recreating only the current React Native runtime.
## Supported behaviors
### `processRestart` (default)
- Android only
- Restarts the app cold and starts again from the splash screen
- Best default for standalone Android apps
```tsx
HotUpdater.setReloadBehavior("processRestart");
```
### `reload`
- Android only
- Uses the normal in-process React Native reload
- Reloads the current React Native screen/runtime instead of restarting the whole app
```tsx
HotUpdater.setReloadBehavior("reload");
```
### `custom`
- Android and iOS
- Runs your own reload logic
- Best when a brownfield host app must reopen a specific native container or screen itself
```tsx
HotUpdater.setReloadBehavior("custom", async () => {
await BrownfieldModule.reload();
});
```
## When to use which
- Use `processRestart` if you want the safest Android default
- Use `reload` in brownfield apps when only the current React Native area should refresh
- Use `custom` in brownfield apps when the host app must coordinate navigation or container restore itself
## Related APIs
- [`HotUpdater.reload()`](/docs/react-native-api/reload)
- [`HotUpdater.wrap()`](/docs/react-native-api/wrap)
# getChannel (https://hot-updater.dev/docs/react-native-api/getChannel)
> The `HotUpdater.getChannel()` function returns the app's current effective channel.
By default, if no channel is specified, the app is assigned to the `production` channel.
For build-time setup, refer to
[Default Channel Setup](/docs/guides/channel-management). For runtime switching,
see [Runtime Channel Switch](/docs/guides/runtime-channel-switch).
## Usage
You can use `HotUpdater.getChannel()` to dynamically check which channel the app is currently using.
### Example
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { Text, View } from "react-native";
function App() {
const channel = HotUpdater.getChannel();
return (
Current Channel: {channel}
);
}
export default HotUpdater.wrap({
baseURL: "",
updateStrategy: "appVersion", // or "fingerprint"
requestHeaders: {
"Authorization": "Bearer ",
},
})(App);
```
## Behavior
- If no runtime channel switch is active, `HotUpdater.getChannel()` returns the build-time channel.
- If a bundle from another channel has been applied at runtime, `HotUpdater.getChannel()` returns that switched channel.
- If no channel is configured, the default is `production`.
- The build-time default channel is injected into the native app during the build process based on `releaseChannel` in `hot-updater.config.ts`.
- Use [`HotUpdater.getDefaultChannel()`](/docs/react-native-api/getDefaultChannel) when you need the embedded default channel regardless of runtime channel switch state.
- You can restore the original channel with [`HotUpdater.resetChannel()`](/docs/react-native-api/resetChannel).
## Configuration Example (`hot-updater.config.ts`)
```tsx
import { defineConfig } from "hot-updater";
import { config } from "dotenv";
config({ path: ".env.hotupdater" });
export default defineConfig({
releaseChannel: "dev", // Specifying the release channel
build: ...,
storage: ...,
database: ...,
});
```
With this configuration, `HotUpdater.getChannel()` will initially return `"dev"`.
## Runtime Example
```tsx
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
channel: "beta",
});
if (updateInfo) {
await updateInfo.updateBundle();
await HotUpdater.reload();
}
console.log(HotUpdater.getChannel()); // "beta"
```
## Related APIs
- [`HotUpdater.checkForUpdate()`](/docs/react-native-api/checkForUpdate)
- [`HotUpdater.getDefaultChannel()`](/docs/react-native-api/getDefaultChannel)
- [`HotUpdater.isChannelSwitched()`](/docs/react-native-api/isChannelSwitched)
- [`HotUpdater.resetChannel()`](/docs/react-native-api/resetChannel)
# getDefaultChannel (https://hot-updater.dev/docs/react-native-api/getDefaultChannel)
> The `HotUpdater.getDefaultChannel()` function returns the build-time default channel embedded in the app.
## Usage
Use `HotUpdater.getDefaultChannel()` when you need the channel embedded in the
native app, even if the app is currently using a runtime channel switch.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
const defaultChannel = HotUpdater.getDefaultChannel();
console.log(defaultChannel);
```
## Behavior
- Returns the build-time default channel configured in the native app
- Does not change when `HotUpdater.checkForUpdate({ channel })` applies a runtime channel switch
- Defaults to `production` when no channel is configured
## Example
```tsx
const currentChannel = HotUpdater.getChannel();
const defaultChannel = HotUpdater.getDefaultChannel();
const switched = HotUpdater.isChannelSwitched();
console.log({ currentChannel, defaultChannel, switched });
```
If the app was built with `production` and later switched to `beta` at runtime:
- `HotUpdater.getChannel()` returns `"beta"`
- `HotUpdater.getDefaultChannel()` returns `"production"`
- `HotUpdater.isChannelSwitched()` returns `true`
## Related APIs
- [`HotUpdater.getChannel()`](/docs/react-native-api/getChannel)
- [`HotUpdater.isChannelSwitched()`](/docs/react-native-api/isChannelSwitched)
- [`HotUpdater.resetChannel()`](/docs/react-native-api/resetChannel)
# getCohort (https://hot-updater.dev/docs/react-native-api/getCohort)
> The `HotUpdater.getCohort()` function returns the persisted cohort used for rollout decisions.
## Usage
Use `HotUpdater.getCohort()` when you want to inspect which cohort the current
device belongs to.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { Text } from "react-native";
function CohortStatus() {
return Current cohort: {HotUpdater.getCohort()};
}
```
## Behavior
- Returns the persisted cohort used for update checks.
- If no cohort has been stored yet, Hot Updater derives an initial numeric
cohort once and persists it before returning.
- Numeric cohorts are in the range `1..1000`.
- Custom cohorts such as `qa` or `dogfood` may also be returned if the app has
previously called `HotUpdater.setCohort()`.
## When to Use
- Show the current cohort in a debug screen
- Copy the current value into the console's `Target Cohorts` field
- Save the initial cohort before temporarily overriding it for QA
## Related APIs
- [`HotUpdater.setCohort()`](/docs/react-native-api/setCohort)
- [Rollout & Cohorts](/docs/guides/rollout-cohorts)
# setCohort (https://hot-updater.dev/docs/react-native-api/setCohort)
> The `HotUpdater.setCohort()` function overrides the persisted cohort used for rollout decisions.
## Usage
Use `HotUpdater.setCohort()` when you want to move a device into a specific
numeric or custom cohort.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
function assignQaCohort() {
HotUpdater.setCohort("qa");
console.log(HotUpdater.getCohort()); // "qa"
}
```
## Behavior
- Persists the cohort on the device for future update checks.
- Accepts numeric cohorts in the range `1..1000`.
- Accepts lowercase slug-style custom cohorts such as `qa` and `vip-testers`.
- Normalizes the value before storing it.
- Throws an error when the value is invalid.
## Important Notes
- Call `HotUpdater.getCohort()` first if you need to restore the previous value
later.
- Percentage rollout applies only to numeric cohorts.
- To keep a custom cohort such as `qa` receiving a bundle alongside numeric
rollout, add that value to `Target Cohorts` in the console. This lets the
same bundle stay available to `qa` even if you later raise numeric rollout
from `0%` to `50%`.
## Related APIs
- [`HotUpdater.getCohort()`](/docs/react-native-api/getCohort)
- [Rollout & Cohorts](/docs/guides/rollout-cohorts)
# isChannelSwitched (https://hot-updater.dev/docs/react-native-api/isChannelSwitched)
> The `HotUpdater.isChannelSwitched()` function returns whether a runtime channel switch is currently active.
## Usage
Use `HotUpdater.isChannelSwitched()` to determine whether the app is currently running with a runtime channel switch instead of its build-time default channel.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
if (HotUpdater.isChannelSwitched()) {
console.log("Using a runtime channel switch");
}
```
## Return Value
Returns `true` when:
- A bundle from another channel was successfully applied at runtime
- The runtime channel switch has not been cleared with `HotUpdater.resetChannel()`
Returns `false` when:
- The app is still on its build-time default channel
- `HotUpdater.resetChannel()` has already cleared the runtime channel switch
## Example
```tsx
const updateInfo = await HotUpdater.checkForUpdate({
updateStrategy: "appVersion",
channel: "staging",
});
if (updateInfo) {
await updateInfo.updateBundle();
await HotUpdater.reload();
}
console.log(HotUpdater.isChannelSwitched()); // true
```
## Related APIs
- [`HotUpdater.getChannel()`](/docs/react-native-api/getChannel)
- [`HotUpdater.checkForUpdate()`](/docs/react-native-api/checkForUpdate)
- [`HotUpdater.resetChannel()`](/docs/react-native-api/resetChannel)
# resetChannel (https://hot-updater.dev/docs/react-native-api/resetChannel)
> The `HotUpdater.resetChannel()` function clears the runtime channel switch and restores the original bundle.
## Usage
Use `HotUpdater.resetChannel()` to discard downloaded OTA state and restore the
bundle selection embedded in the native app. The reset runs even when no
runtime channel override is active.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
async function handleResetChannel() {
const didReset = await HotUpdater.resetChannel();
if (didReset) {
await HotUpdater.reload();
}
}
```
## Behavior
- Clears any runtime channel override and makes the build-time default channel
active again.
- Clears downloaded OTA bundle metadata, launch state, and downloaded bundle
directories. Crash history is preserved.
- Restores built-in bundle selection. Call `HotUpdater.reload()` to load that
bundle in the current app session.
- Runs the native reset regardless of the value returned by
`HotUpdater.isChannelSwitched()`.
- Resolves to `true` when the reset succeeds. A native reset failure can resolve
to `false` or reject with an error.
## Example
```tsx
const didReset = await HotUpdater.resetChannel();
if (didReset) {
await HotUpdater.reload();
}
```
## When to Use
- Leave a beta or staging runtime channel switch
- Add a "Return to default channel" action in a debug or settings screen
- Recover to the original shipped bundle after testing another channel
## Related APIs
- [`HotUpdater.getChannel()`](/docs/react-native-api/getChannel)
- [`HotUpdater.isChannelSwitched()`](/docs/react-native-api/isChannelSwitched)
- [`HotUpdater.checkForUpdate()`](/docs/react-native-api/checkForUpdate)
# getAppVersion (https://hot-updater.dev/docs/react-native-api/getAppVersion)
> The `HotUpdater.getAppVersion()` function returns the current native app version embedded at build time.
## Usage
Use `HotUpdater.getAppVersion()` to read the app version from the native build.
This is useful for diagnostics, showing version info in settings screens, and
custom updates.
```tsx
import { HotUpdater } from "@hot-updater/react-native";
import { Text, View } from "react-native";
function App() {
const appVersion = HotUpdater.getAppVersion();
return (
App Version: {appVersion ?? "unknown"}
);
}
export default App;
```
## Return Value
```ts
getAppVersion(): string | null
```
- Returns a version string when available (for example: `"1.2.3"`).
- Returns `null` when the native constant is unavailable.
## Behavior
- `getAppVersion()` is synchronous.
- The value is sourced from native app metadata:
- iOS: `CFBundleShortVersionString` in `Info.plist`
- Android: `PackageInfo.versionName`
- The native module then exposes this as `APP_VERSION`, and
`HotUpdater.getAppVersion()` returns that bridged value.
- It does **not** make a network request.
# useHotUpdaterStore (https://hot-updater.dev/docs/react-native-api/useHotUpdaterStore)
> Read update progress from React components.
Use `useHotUpdaterStore` when you want to show OTA update progress in your
React Native UI.
For most apps, `progress` and `isUpdateDownloaded` are enough. Use
`artifactType` and `details` only when you want to render bundle diffing
progress more specifically.
## Basic Usage
`progress` is a number from `0` to `1`. `isUpdateDownloaded` becomes `true`
when the update has finished downloading and can be applied with
`HotUpdater.reload()`.
```tsx
import { HotUpdater, useHotUpdaterStore } from "@hot-updater/react-native";
import { Button, Text, View } from "react-native";
function App() {
const { progress, isUpdateDownloaded } = useHotUpdaterStore();
return (
{Math.round(progress * 100)}%
);
}
```
## State
| Field | Type | Description |
|----------------------|-----------------------|--------------------------------------------------|
| `progress` | `number` | Overall update progress from `0` to `1`. |
| `isUpdateDownloaded` | `boolean` | `true` when `progress` reaches `1`. |
| `artifactType` | `"archive" \| "diff" \| null` | Current download type, or `null` before progress starts. |
| `downloadedBytes` | `number \| undefined` | Downloaded bytes for archive updates. |
| `totalBytes` | `number \| undefined` | Total bytes for archive updates when known. |
| `details` | `object \| null` | Per-file progress for bundle diffing updates. |
When `artifactType` is `"archive"`, the app is downloading the normal
compressed OTA archive.
When `artifactType` is `"diff"`, Hot Updater is reusing unchanged files from
the current OTA bundle and downloading only the files that changed. In this
case, `details` contains `totalFilesCount`, `completedFilesCount`, and `files`.
```tsx
import { useHotUpdaterStore } from "@hot-updater/react-native";
import { Text, View } from "react-native";
function UpdateProgress() {
const { artifactType, details, progress } = useHotUpdaterStore();
return (
{Math.round(progress * 100)}%
{artifactType === "diff" && details ? (
{details.completedFilesCount}/{details.totalFilesCount} files
) : null}
);
}
```
## Optimizing Renders with Selectors
Pass a selector when a component only needs one field from the store.
```tsx
import { HotUpdater, useHotUpdaterStore } from "@hot-updater/react-native";
import { Button, Text } from "react-native";
function ProgressDisplay() {
const progress = useHotUpdaterStore((state) => state.progress);
return {Math.round(progress * 100)}%;
}
function UpdateButton() {
const isUpdateDownloaded = useHotUpdaterStore(
(state) => state.isUpdateDownloaded,
);
return (
![]({"/docs/rollout-cohorts/get-cohort-ios.png"})
In this example, `HotUpdater.getCohort()` returns `411`, so this device belongs
to cohort `411`.
### Preview the Selected Numeric Cohorts
Assume you deploy the bundle with a `50%` rollout:
```package-install
npx hot-updater deploy -p ios -r 50
```
Open the bundle in the console and click `Preview Cohorts`:
![]({"/docs/rollout-cohorts/preview_411.png"})
This opens the numeric cohort preview for that bundle:
![]({"/docs/rollout-cohorts/preview_cohort.png"})
If rollout is `50.0%`, Hot Updater selects `500` numeric cohorts out of
`1..1000`. That selection is based on the bundle's `bundleId`, so the result is
stable for that bundle.
`50%` rollout does not mean cohorts `1..500`. Hot Updater uses a stable
shuffled set per bundle, and `Preview Cohorts` shows the exact numeric cohorts
selected for that rollout.
You can read the result like this:
| Check | Example | Result |
| ---------------------------- | --------------------------------- | ------------------------------------------------------ |
| Device cohort | `HotUpdater.getCohort() = 411` | This device belongs to cohort `411`. |
| Rollout percentage | `50.0%` | The bundle targets `500` of `1000` numeric cohorts. |
| Cohort excluded from preview | `410` is not in the selected list | A device in cohort `410` does not receive this bundle. |
| Cohort included in preview | `411` is in the selected list | A device in cohort `411` does receive this bundle. |
Here is the direct check for cohort `411`:
![]({"/docs/rollout-cohorts/final-current-state.png"})
This walkthrough shows the normal numeric rollout flow:
1. The device starts with cohort `411`.
2. You deploy with `npx hot-updater deploy -p ios -r 50`.
3. The preview confirms that cohort `411` is included.
4. The device is eligible, so it receives the bundle.
This is why the preview is useful: percentage rollout is not a simple `1..500`
range. Hot Updater keeps a stable shuffled set per bundle, and `Preview
Cohorts` shows the exact numeric cohorts included in that rollout.
## Scenario 2: Manual Cohort Override and Target Cohorts
Use this flow when you want a fixed tester group to keep receiving the bundle
while numeric rollout continues for the rest of the audience.
This is useful because numeric rollout picks a stable but bundle-specific
numeric cohort set. A tester device may or may not be in that set.
`Target Cohorts` lets you keep a known group such as `qa` included throughout
rollout.
In this example, tester devices use cohort `qa`, and the bundle keeps
`Rollout Percentage = 50.0%` while also targeting `qa`.
You can use the same flow with a numeric cohort such as `411`.
This is the device state after setting the cohort to `qa`:
![]({"/docs/rollout-cohorts/set_cohort.png"})
In this example, the app UI shows `HotUpdater.getCohort() = qa`.
### Set the Device Cohort
Use `HotUpdater.setCohort()` to make the device act like a specific cohort:
```tsx
import { HotUpdater } from "@hot-updater/react-native";
function assignQaCohort() {
HotUpdater.setCohort("qa");
console.log("Active cohort:", HotUpdater.getCohort());
}
```
```tsx
import { HotUpdater } from "@hot-updater/react-native";
function assignNumericCohort() {
HotUpdater.setCohort("411");
console.log("Active cohort:", HotUpdater.getCohort());
}
```
You can set either kind of cohort:
- `HotUpdater.setCohort("qa")` puts the device in a named tester group.
- `HotUpdater.setCohort("411")` makes the device behave like numeric cohort
`411`.
- A numeric override is useful when you want a tester device to follow a bundle
that is already rolling out to a known numeric cohort.
If you want to restore the original cohort later, read it with
`HotUpdater.getCohort()` and save it before calling `setCohort()`.
### Target Specific Cohorts from the Console
If you want numeric rollout and a fixed tester group at the same time, keep
both on the same bundle. A common flow is:
1. Deploy the bundle with `-r 0`.
2. Add `qa` to `Target Cohorts`.
3. After QA verifies the bundle, increase the same bundle to `50%` rollout.
You can do the same thing from the CLI:
```package-install
npx hot-updater bundle update ![]({"/docs/rollout-cohorts/target_cohorts_with50.png"})
In this example, the bundle is configured like this:
- `Rollout Percentage = 50.0%`
- `Target Cohorts = qa`
`Target Cohorts` supports both custom cohorts like `qa` and numeric values like
`411`. Think of it as an explicit cohort list: you can put existing numeric
cohorts and custom cohorts in the same place.
`Rollout Percentage` and `Target Cohorts` work together.
- Numeric rollout still applies to the selected numeric cohorts for this
bundle.
- `Target Cohorts` adds extra cohorts such as `qa` or `411`.
You may see both settings in the console at the same time, as in the screenshot
above. In this state, the numeric `50.0%` rollout still applies to the bundle's
selected numeric cohorts, and devices in `qa` are also included.
This is useful in two common cases:
- Deploy with `-r 0` and `Target Cohorts = qa` when you want to test the bundle
with QA first.
- Raise the same bundle to `50%` later and keep `qa` in `Target Cohorts` so
the main rollout and QA testing continue together.
You can read the result like this:
| Check | Example | Result |
| ------------------------------ | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| Numeric rollout device | `HotUpdater.getCohort() = 411`, and `411` is in `Preview Cohorts` | This device receives the bundle through numeric rollout. |
| QA tester device | `HotUpdater.getCohort() = qa` | This device receives the bundle because `qa` is in `Target Cohorts`. |
| Numeric cohort outside rollout | `HotUpdater.getCohort() = 410`, and `410` is not in `Preview Cohorts` | This device does not receive the bundle unless `410` is also added to `Target Cohorts`. |
| Other custom cohort | `HotUpdater.getCohort() = dogfood` | This device does not receive the bundle unless `dogfood` is targeted. |
Use this flow when you want stable tester coverage without giving up gradual
numeric rollout. If needed, you can do the same thing with a numeric cohort
such as `411`.
### Manual Override Flow
1. Read the current cohort on the tester device with `HotUpdater.getCohort()`.
2. Change it to `qa` with `HotUpdater.setCohort()`. If you want to match a
numeric rollout instead, use a value such as `411`.
3. Deploy the bundle with `npx hot-updater deploy -p ios -r 0` and set
`Target Cohorts = qa` so only QA devices receive it first.
4. After QA confirms the bundle, increase rollout to `50%` and keep `qa` in
`Target Cohorts` on the same bundle.
5. Devices in the selected numeric rollout keep receiving the bundle, and QA
devices in `qa` also keep receiving it.
## Related APIs
- [`HotUpdater.getCohort()`](/docs/react-native-api/getCohort)
- [`HotUpdater.setCohort()`](/docs/react-native-api/setCohort)
- [Deploy](/docs/guides/deploy)
- [Console](/docs/guides/console)
# Console (Rollback & Force Update) (https://hot-updater.dev/docs/guides/console)
> Opens a localhost server based on plugins configured in `hot-updater.config.ts`. For security reasons, only localhost server is supported at the moment.
**The console provides the following features:**
- Rollback
- Force update flag
- Quick access to git history for updates
## Configuration (Optional)
This is a console configuration that does not affect the bundle.
You can configure additional console settings in the `hot-updater.config.ts` file.
The `storage` and `database` plugins must be exist.
| Option | Description | Default |
| ---------------- | -------------------------------------------------------- | ------- |
| `console.gitUrl` | Enables commit shortcuts by linking to git commit hashes | - |
| `console.port` | Sets the console server port | `1422` |
```ts title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
console: { // [!code hl]
port: 3000, // [!code hl]
}, // [!code hl]
build: ...,
storage: ...,
database: ...,
});
```
## Usage
Execute the following command:
```package-install
npx hot-updater console
```
You can also use the bundle CLI for automation and CI scripts:
```package-install
npx hot-updater bundle list -p ios
npx hot-updater bundle show ![]({"/docs/console/enabled.png"})
## Force Update
When you set a bundle's `shouldForceUpdate` status to `true` in the console, users who have that bundle will immediately force update to the **latest bundle**.
![]({"/docs/console/force_update.png"})
## Git URL
You can set the git URL in the `hot-updater.config.ts` file.
```ts title="hot-updater.config.ts"
import { defineConfig } from "hot-updater";
export default defineConfig({
console: {
gitUrl: "![]({"/docs/console/git_url.png"})
# Storage Cleanup (https://hot-updater.dev/docs/guides/storage-cleanup)
> Safely reclaim unreferenced bundle artifacts and shared assets with the storage prune command.
## How pruning works
`hot-updater storage prune` is reference-aware garbage collection. It reads all
bundle records and their manifests, lists the configured storage prefix, and
selects only objects that are no longer referenced.
It can remove:
- Orphaned bundle objects in both the legacy `