Getting started#

This guide takes an existing React Native app from no Rollbird configuration to a verified preview update, a rollback, and a production-ready channel.

Availability: @rollbird/cli and @rollbird/react-native are public npm packages. The commands below install and run the released packages.

Before you begin#

You need Node.js 20 or newer, a Rollbird account, and a React Native app whose native iOS or Android build already runs on a device or simulator.

React Native 0.76 is the currently verified baseline. The package declares no narrower React Native peer range, so that is a tested version rather than a formal minimum. Expo projects require Expo 50 or newer. iOS requires a target of 13.4 or newer through the pinned native client. Android inherits the app's existing minSdkVersion and compileSdkVersion.

Decide which build you are configuring:

Use preview for a simulator, internal build, or test device.
Use production only for the binary distributed to end users.

A channel is embedded in the native binary. Publishing to another channel does not retarget that installed build.

1. Install the CLI#

Run this from the React Native project root, beside package.json:

npm install --save-dev @rollbird/cli

This adds the rollbird executable to node_modules/.bin, so every following command uses npx rollbird.

Verify the command surface:

npx rollbird --help

Expected command names:

login
init
release
rollback
status

If npm reports a package-not-found error, see npm install returns 404.

Start device authorization:

npx rollbird login

The CLI prints a one-time code and a dashboard URL. In an interactive terminal, press Enter to open the prefilled page, compare the browser code with the terminal, choose the organization, and confirm.

Expected completion:

✓ Confirmed  in the browser

Logged in

Credentials are written with mode 0600 to ~/.config/rollbird/credentials.json, or to $XDG_CONFIG_HOME/rollbird/credentials.json when XDG_CONFIG_HOME is set. Do not commit that file.

CI does not use the device flow. Use a scoped token as described in CI/CD.

3. Configure a preview build#

From the project root, run:

npx rollbird init --channel preview

init detects bare React Native or Expo, links an existing matching app identifier or creates a project, provisions its signing key, installs the SDK dependencies, writes native configuration, and creates rollbird.json.

A bare React Native project ends with output shaped like:

✓ React Native  Android · iOS · Hermes
✓ Linked  your-project
✓ Signing key  ready
✓ Native config  preview channel
✓ SDK  installed with npm
✓ Entry points  wired
✓ Fingerprints  embedded

Ready to ship

An Expo project instead reports its config plugin and stored fingerprints:

✓ Expo  app.json · native code generated by prebuild
✓ Linked  your-project
✓ Signing key  ready
✓ Plugin  registered in app.json
✓ SDK  installed with npm
✓ Fingerprints  stored in rollbird.json
✓ Config  preview channel → rollbird.json

Ready to ship

Commit rollbird.json. It contains the project id and public project key, not an API token or private signing key. On Expo it also contains the channel, public signing key, runtime, and per-platform fingerprints required by the config plugin.

Do not do this: Do not install expo-updates alongside Rollbird. Both packages control application updates; rollbird init refuses that setup.

4. Wrap the app component#

Open the module that currently exports the root App component. In a standard React Native app this is usually App.tsx at the project root. Keep the existing component and replace only its final default export.

Add the import with the other imports:

import { Rollbird } from "@rollbird/react-native";

At the existing default export, wrap App with the projectKey written in rollbird.json:

export default Rollbird.wrap({ projectKey: "pk_from_rollbird_json" })(App);

Do not put the API token here. projectKey is public app configuration; the CLI token is a secret.

5. Complete Expo configuration#

Skip this section for a bare React Native app.

When the project uses app.json, rollbird init writes this plugin entry for you:

{
  "expo": {
    "plugins": [
      ["@rollbird/react-native", { "channel": "preview" }]
    ]
  }
}

When the project uses app.config.js or app.config.ts, the file is code and Rollbird does not rewrite it. Add the same plugin entry to the plugins array returned by that file.

Generate the native projects or let EAS Build do so:

npx expo prebuild

Re-run rollbird init after adding or changing a native dependency. It refreshes the stored fingerprint that the next prebuild embeds.

6. Rebuild the native app#

This step is required. An already-installed binary does not contain the Rollbird native module, channel, signing key, or fingerprint.

Build iOS with the command your project already uses, for example:

npx react-native run-ios --mode Release

Build Android with the command your project already uses, for example:

npx react-native run-android --mode release

For Expo, use the project's normal local or EAS native-build workflow after prebuild. A development server session does not prove OTA behavior; install a release or internal-distribution binary.

These native builds were not run while authoring this guide because they need the consumer app's Xcode/Android toolchain, signing configuration, and device.

7. Publish the first preview release#

Make a visible JavaScript-only change, then publish to the preview channel:

npx rollbird release

preview is the default release channel. The CLI bundles each detected platform, signs and uploads the archives, then publishes the release.

Expected completion:

✓ Bundled iOS  977 KB
✓ Bundled Android  980 KB
✓ Signed  2 bundles
✓ Uploaded  1.9 MB
✓ Published  Release #1 · 100% rollout

Live in preview

Bundle sizes vary. The release number and dashboard URL in the real output are the values to verify.

8. Verify on a device#

Launch the preview binary while it has network access.
Let the update check and background download complete.
Close and relaunch the app.
Confirm the JavaScript-only change appears.
Open the release URL printed by the CLI and confirm the release is active.

Without a custom fallbackComponent, a normal update downloads in the background and runs on the next launch. A release published with --force reloads automatically after download unless reloadOnForceUpdate is set to false in Rollbird.wrap.

9. Verify rollback#

Rollback the active preview release:

npx rollbird rollback --channel preview

Confirm the prompt. Expected completion:

✓ Rolled back  release #1

Now serving the embedded bundle on preview

If an earlier active preview release exists, the final line names that release instead. Launch the app, allow the rollback bundle to download, and relaunch.

Rollback is instant and free. It never consumes release quota and remains available when plan status or storage blocks a new release.

10. Prepare production#

The preview channel is baked into the build made above. Reconfigure before creating the store binary:

npx rollbird init --channel production

For Expo, apply the refreshed configuration:

npx expo prebuild

Build, test, sign, and distribute the production binary through the stores. After users have that binary, publish a production update:

npx rollbird release --production

The command asks for confirmation in an interactive terminal. CI must add --yes explicitly.

Do not do this#

Do not publish preview updates to a production-channel binary and expect it to receive them.
Do not skip the native rebuild after first setup or native dependency changes.
Do not put ROLLBIRD_TOKEN in rollbird.json, application code, or CI workflow YAML.
Do not combine Rollbird with expo-updates or another update controller.
Do not treat Hermes as a switch Rollbird chooses. Rollbird detects the app's engine and uses that app's compiler.
Do not delay rollback because a quota is exhausted. Rollback is always available and free.

View this page as Markdown