# Coding agent integration

Use this guide when a coding agent is adding Rollbird to an existing React
Native or Expo repository. It narrows the full [Getting started](https://rollbird.dev/docs/getting-started/)
flow to the decisions, edits, and verification evidence an agent needs.

The [CLI reference](https://rollbird.dev/docs/cli/) and
[React Native SDK guide](https://rollbird.dev/docs/react-native/) remain the
sources of truth for command flags and runtime options. Do not invent a flag,
native path, or configuration value when those guides do not describe it.

## Integration contract

A complete integration has four parts:

1. `@rollbird/cli` is installed as a development dependency.
2. `rollbird init --channel preview` has linked the project and written public configuration.
3. The existing root component export is wrapped with `Rollbird.wrap`.
4. A newly rebuilt native binary receives a preview update and can roll it back.

The project key in `rollbird.json` is public app configuration. An API token,
CLI credential, or signing private key is a secret and must never be copied
into `rollbird.json`, application code, logs, or a committed CI workflow.

## 1. Inspect before changing anything

Read the repository's agent instructions and check its working tree before
editing. Preserve unrelated changes and use the package manager already
selected by the repository lockfile.

Inspect these files when they exist:

- `package.json` and the repository lockfile.
- `rollbird.json`; if present, treat the app as already linked and understand its current channel before running `init` again.
- `app.json`, `app.config.js`, or `app.config.ts` for Expo projects.
- The module that owns the root `App` default export.
- `ios/` and `android/` for a bare React Native app or an Expo app with generated native projects.

Determine whether the app is bare React Native or Expo, whether each platform
uses Hermes, and which command already builds a release or internal-distribution
binary. Do not replace the app's established native-build workflow.

> **Stop:** If `expo-updates` or another OTA controller is installed, do not
> add Rollbird beside it. Explain the conflict and ask the developer which
> update system to keep.

## 2. Confirm prerequisites

Rollbird's CLI and build tooling require Node.js 20 or newer. React Native 0.76
is the verified baseline. Expo projects require Expo 50 or newer and
`@expo/config-plugins` 9 or newer.

Check the active Node.js version:

```bash
node --version
```

If the version is below 20, stop and ask the developer to switch the project
to a supported Node.js version before continuing.

## 3. Install and authenticate

Install `@rollbird/cli` as a development dependency using the repository's
existing package manager. For npm:

```bash
npm install --save-dev @rollbird/cli
```

Authentication is a human checkpoint. Ask the developer to run the device
authorization flow and confirm the browser code:

```bash
npx rollbird login
```

Do not capture, print, commit, or copy the credential file. CI uses a scoped
`ROLLBIRD_TOKEN` from its secret store instead; see
[CI/CD](https://rollbird.dev/docs/ci/).

## 4. Initialize a preview build

Before running `init`, get the developer's confirmation: it can link an
existing Rollbird project or create one, provision signing, install SDK
dependencies, and modify native or Expo configuration. Use `preview` for the
first integration:

```bash
npx rollbird init --channel preview
```

After the command completes, inspect the working-tree diff. Keep the generated
`rollbird.json`; it contains the linked project id and public configuration.
Never substitute guessed ids, keys, fingerprints, or signing values.

For an Expo project with `app.config.js` or `app.config.ts`, the CLI does not
rewrite executable configuration. Add the generated plugin entry to the
existing `plugins` array while preserving the rest of the returned config:

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

Do not add that entry a second time when it already exists.

## 5. Wrap the existing root component

Edit the module that already exports the root `App` component. Add the SDK
import with the existing imports:

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

Replace only the existing default export, using the exact public project key
written to `rollbird.json`:

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

Preserve providers, navigation containers, error boundaries, and the component
body. If the export is not shaped like this example, adapt the wrapper to the
existing component instead of restructuring the application.

## 6. Review before native work

Before asking for a build, verify the diff has these properties:

- The package manager changed only its expected manifest and lockfile entries.
- `rollbird.json` contains public project configuration and no token or private key.
- The root component is wrapped exactly once.
- Expo has one Rollbird plugin entry, or the bare native targets contain the generated configuration.
- Existing OTA packages were not left installed beside Rollbird.
- No unrelated application or native code was changed.

Run the repository's existing tests, typecheck, and lint commands. Report the
exact commands and results; do not claim native or on-device verification from
JavaScript tests alone.

## 7. Rebuild and verify on a device

The developer must create and install a new native binary. Reloading Metro or
restarting an old binary cannot verify the integration because that binary
lacks the new native module, channel, signing key, and fingerprint.

For Expo, apply the config plugin before the native build:

```bash
npx expo prebuild
```

Use the repository's normal release or internal-distribution build command.
Native signing, store credentials, EAS access, simulators, and physical devices
remain human or environment checkpoints when the agent does not have them.

With explicit approval to publish and test rollback, make a visible
JavaScript-only change and create the first preview release:

```bash
npx rollbird release
```

Launch the installed preview binary with network access, allow the update to
download, relaunch, and confirm the change appears. Then verify recovery:

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

Rollback is always free, does not consume release quota, and remains available
when plan status or storage prevents a new release.

## Agent handoff checklist

When returning the work to the developer, state:

- Which project type, package manager, channel, and root component were detected.
- Which files changed and why.
- Which automated checks ran and their real results.
- Whether a native binary was rebuilt and installed.
- Whether an update and rollback were verified on a device.
- Every remaining human checkpoint, such as login, native signing, publishing approval, or store distribution.

Do not report the integration as complete until the native rebuild and device
update are verified. If those steps are unavailable, describe the code changes
as ready for native verification instead.