# 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`:

```bash
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:

```bash
npx rollbird --help
```

Expected command names:

```text
login
init
release
rollback
status
```

If npm reports a package-not-found error, see [npm install returns 404](https://rollbird.dev/docs/troubleshooting/#npm-install-returns-404).

## 2. Sign in

Start device authorization:

```bash
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:

```text
✓ 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](https://rollbird.dev/docs/ci/).

## 3. Configure a preview build

From the project root, run:

```bash
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:

```text
✓ 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:

```text
✓ 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:

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

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

```tsx
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:

```json
{
  "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:

```bash
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:

```bash
npx react-native run-ios --mode Release
```

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

```bash
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:

```bash
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:

```text
✓ 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

1. Launch the preview binary while it has network access.
2. Let the update check and background download complete.
3. Close and relaunch the app.
4. Confirm the JavaScript-only change appears.
5. 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:

```bash
npx rollbird rollback --channel preview
```

Confirm the prompt. Expected completion:

```text
✓ 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:

```bash
npx rollbird init --channel production
```

For Expo, apply the refreshed configuration:

```bash
npx expo prebuild
```

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

```bash
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.