Javascript Reference (API)

The CodePush plugin has two components:

1. JavaScript module - Interact with the service at runtime (check updates, inspect metadata)
2. Native API (Objective-C/Java) - Bootstrap the app with the correct JS bundle location

Top-level Methods

When you import react-native-code-push, you get these methods:

Method	Description
allowRestart	Re-allows programmatic restarts after disallowRestart
checkForUpdate	Check if an update is available
disallowRestart	Temporarily block restarts during critical flows
getUpdateMetadata	Get metadata about installed updates
notifyAppReady	Mark update as successful (prevents rollback)
restartApp	Immediately restart the app
sync	Check, download, and install updates in one call
clearUpdates	Clear all downloaded updates. Note: we don’t recommend using this method in scenarios other than OTA debugging/testing; CodePush will call it automatically when appropriate. Using it in other cases could lead to unpredictable behavior.

codePush

// Wrapper function
codePush(rootComponent: React.Component): React.Component;
codePush(options: CodePushOptions)(rootComponent: React.Component): React.Component;

Wraps a React component to automatically sync updates on mount. Internally calls sync in componentDidMount.

Usage Examples

1. Silent sync on app start (default behavior)

Updates download silently and apply on next restart.

const MyApp = () => <App />;
export default codePush(MyApp);

2. Silent sync on every resume

const MyApp = () => <App />;

export default codePush({
  checkFrequency: codePush.CheckFrequency.ON_APP_RESUME,
  installMode: codePush.InstallMode.ON_NEXT_RESUME
})(MyApp);

3. Interactive with prompt

Prompts user before downloading. Mandatory updates show notification but can't be ignored.

const MyApp = () => <App />;

export default codePush({
  updateDialog: true,
  installMode: codePush.InstallMode.IMMEDIATE
})(MyApp);

4. With progress tracking

const MyApp = () => {
  const codePushStatusDidChange = (status) => {
    const messages = {
      [codePush.SyncStatus.CHECKING_FOR_UPDATE]: "Checking for updates.",
      [codePush.SyncStatus.DOWNLOADING_PACKAGE]: "Downloading package.",
      [codePush.SyncStatus.INSTALLING_UPDATE]: "Installing update.",
      [codePush.SyncStatus.UP_TO_DATE]: "Up-to-date.",
      [codePush.SyncStatus.UPDATE_INSTALLED]: "Update installed.",
    };
    console.log(messages[status] || "Unknown status");
  };

  const codePushDownloadDidProgress = ({ receivedBytes, totalBytes }) => {
    console.log(`${receivedBytes} of ${totalBytes} received.`);
  };

  return <App />;
};

// Attach hooks as static properties
MyApp.codePushStatusDidChange = codePushStatusDidChange;
MyApp.codePushDownloadDidProgress = codePushDownloadDidProgress;

export default codePush(MyApp);

CodePushOptions

Option	Type	Default	Description
checkFrequency	CheckFrequency	ON_APP_START	When to check for updates
deploymentKey	String	From config	Override deployment key at runtime
installMode	InstallMode	ON_NEXT_RESTART	When to install optional updates
mandatoryInstallMode	InstallMode	IMMEDIATE	When to install mandatory updates
minimumBackgroundDuration	Number	0	Seconds in background before restart (for ON_NEXT_RESUME/ON_NEXT_SUSPEND)
updateDialog	UpdateDialogOptions	null	Configure update prompt dialog
rollbackRetryOptions	RollbackRetryOptions	null	Configure rollback retry behavior

UpdateDialogOptions

Option	Default	Description
appendReleaseDescription	false	Append release description to notification
descriptionPrefix	" Description: "	Prefix for release description
mandatoryContinueButtonLabel	"Continue"	Button text for mandatory updates
mandatoryUpdateMessage	"An update is available that must be installed."	Message for mandatory updates
optionalIgnoreButtonLabel	"Ignore"	Ignore button text
optionalInstallButtonLabel	"Install"	Install button text
optionalUpdateMessage	"An update is available. Would you like to install it?"	Message for optional updates
title	"Update available"	Dialog title

RollbackRetryOptions

The rollback retry mechanism allows the application to attempt to reinstall an update that was previously rolled back (with the restrictions specified in the options).

Option	Default	Description
delayInHours	24	Minimum hours before retrying rolled-back update
maxRetryAttempts	1	Maximum retry attempts (min: 1)

Event Hooks

codePushStatusDidChange

Called when sync moves between stages. Receives a SyncStatus code.

codePushDownloadDidProgress

Called periodically during download with:

• totalBytes - Total bytes to download
• receivedBytes - Bytes downloaded so far

---

codePush.allowRestart

codePush.allowRestart(): void;

Re-allows restarts after disallowRestart. If an update was pending restart, it triggers immediately.

Won't trigger restart if:

• No updates installed since disallowRestart
• Pending update uses ON_NEXT_RESTART mode
• Pending update uses ON_NEXT_RESUME but app hasn't backgrounded yet
• No restartApp calls since disallowRestart

---

codePush.checkForUpdate

codePush.checkForUpdate(
  deploymentKey?: string,
  handleBinaryVersionMismatchCallback?: (update: RemotePackage) => void
): Promise<RemotePackage | null>;

Checks if an update is available.

Returns null when:

• No releases in deployment
• Latest release targets different binary version
• App already has latest release
• Latest release is disabled
• Device not in active rollout percentage

Returns RemotePackage when update is available.

const update = await codePush.checkForUpdate();

if (!update) {
  console.log("The app is up to date!");
} else {
  console.log("An update is available! Should we download it?");
}

The optional handleBinaryVersionMismatchCallback notifies when binary updates are available (e.g., installed 1.0.1 but 1.0.2 exists).

App Store Note

Be cautious using Alerts in this callback for iOS apps due to App Store guidelines about forced actions.

---

codePush.disallowRestart

codePush.disallowRestart(): void;

Temporarily blocks restarts from:

1. Updates with InstallMode.IMMEDIATE
2. Updates with ON_NEXT_RESUME when app resumes
3. Direct restartApp calls

Useful for protecting critical flows like onboarding.

const OnboardingProcess = () => {
  useEffect(() => {
    // Block restarts during onboarding
    codePush.disallowRestart();
    
    return () => {
      // Re-allow on unmount (triggers pending restart if any)
      codePush.allowRestart();
    };
  }, []);

  return <OnboardingContent />;
};

---

codePush.getUpdateMetadata

codePush.getUpdateMetadata(
  updateState: UpdateState = UpdateState.RUNNING
): Promise<LocalPackage | null>;

Gets metadata for installed updates matching the specified state.

Returns null when:

• No CodePush updates installed yet
• Binary update cleared old CodePush updates
• RUNNING requested but no CodePush update is running
• PENDING requested but no pending updates

// Get running update info
const update = await codePush.getUpdateMetadata();
if (update) {
  analytics.track({ CodePushRelease: update.label });
}

// Check for pending updates
const pending = await codePush.getUpdateMetadata(codePush.UpdateState.PENDING);
if (pending) {
  // Maybe force restart?
}

---

codePush.notifyAppReady

codePush.notifyAppReady(): Promise<void>;

Marks the current update as successful, preventing automatic rollback on next restart.

tip

If using sync, this is called automatically. Only needed for manual update flows.

---

codePush.restartApp

codePush.restartApp(onlyIfUpdateIsPending?: boolean): void;

Immediately restarts the app. If onlyIfUpdateIsPending is true, only restarts if there's a pending update.

Useful when using ON_NEXT_RESTART/ON_NEXT_RESUME modes and you have a good moment to apply updates (e.g., user returns to home screen).

---

codePush.sync

codePush.sync(
  options?: SyncOptions,
  syncStatusChangeCallback?: (status: SyncStatus) => void,
  downloadProgressCallback?: (progress: DownloadProgress) => void,
  handleBinaryVersionMismatchCallback?: (update: RemotePackage) => void
): Promise<SyncStatus>;

All-in-one method: checks, downloads, and installs updates.

Two modes:

1. Silent (default) - Downloads silently, applies on next restart
2. Active - Prompts user, applies immediately

// Silent update
codePush.sync();

// Active with prompt
codePush.sync({
  updateDialog: true,
  installMode: codePush.InstallMode.IMMEDIATE
});

SyncOptions

Same as CodePushOptions except checkFrequency.

// Different deployment key
codePush.sync({ deploymentKey: "KEY" });

// Install on resume after 5 min in background
codePush.sync({
  installMode: codePush.InstallMode.ON_NEXT_RESUME,
  minimumBackgroundDuration: 300
});

// Optional on restart, mandatory on resume
codePush.sync({
  mandatoryInstallMode: codePush.InstallMode.ON_NEXT_RESUME
});

// Custom dialog
codePush.sync({
  updateDialog: {
    title: "An update is available!",
    appendReleaseDescription: true,
    descriptionPrefix: "\n\nChange log:\n"
  },
  installMode: codePush.InstallMode.IMMEDIATE
});

With callbacks

codePush.sync(
  { updateDialog: true },
  (status) => {
    if (status === codePush.SyncStatus.DOWNLOADING_PACKAGE) {
      showDownloadModal();
    } else if (status === codePush.SyncStatus.INSTALLING_UPDATE) {
      hideDownloadModal();
    }
  },
  ({ receivedBytes, totalBytes }) => {
    updateProgress(receivedBytes / totalBytes);
  }
);

Return values

Status	Value	Description
UP_TO_DATE	0	App is up-to-date
UPDATE_INSTALLED	1	Update installed, will apply based on InstallMode
UPDATE_IGNORED	2	User ignored optional update
SYNC_IN_PROGRESS	4	Another sync is already running

---

Package Objects

LocalPackage

Represents a downloaded/installed update. Get via getUpdateMetadata or RemotePackage.download.

Properties

Property	Type	Description
appVersion	String	Target binary version
deploymentKey	String	Deployment key used
description	String	Release description
failedInstall	Boolean	Was this update rolled back before?
isFirstRun	Boolean	First run after install?
isMandatory	Boolean	Is mandatory update?
isPending	Boolean	Installed but not yet applied?
label	String	Internal label (e.g., v5)
packageHash	String	SHA hash
packageSize	Number	Size in bytes

Methods

await localPackage.install(
  installMode?: InstallMode,      // default: ON_NEXT_RESTART
  minimumBackgroundDuration?: number  // default: 0
): Promise<void>;

RemotePackage

Represents an available update on the server. Get via checkForUpdate.

Inherits all LocalPackage properties plus:

Property	Type	Description
downloadUrl	String	URL to download the update

Methods

const localPackage = await remotePackage.download(
  downloadProgressCallback?: (progress: DownloadProgress) => void
): Promise<LocalPackage>;

---

Enums

InstallMode

Value	Code	Description
IMMEDIATE	0	Install and restart immediately
ON_NEXT_RESTART	1	Install now, apply on natural restart (default)
ON_NEXT_RESUME	2	Install now, apply when app resumes from background
ON_NEXT_SUSPEND	3	Install while in background (after minimumBackgroundDuration)

CheckFrequency

Value	Code	Description
ON_APP_START	0	Check on app process start
ON_APP_RESUME	1	Check when app returns from background
MANUAL	2	Only check when sync() is called

SyncStatus

Value	Code	Description
UP_TO_DATE	0	App is up-to-date
UPDATE_INSTALLED	1	Update installed
UPDATE_IGNORED	2	User ignored optional update
UNKNOWN_ERROR	3	Unknown error occurred
SYNC_IN_PROGRESS	4	Another sync is running
CHECKING_FOR_UPDATE	5	Querying server
AWAITING_USER_ACTION	6	Waiting for user response to dialog
DOWNLOADING_PACKAGE	7	Downloading update
INSTALLING_UPDATE	8	Installing update

UpdateState

Value	Code	Description
RUNNING	0	Currently running update
PENDING	1	Installed but pending restart
LATEST	2	Latest available (running or pending)