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 flow to the decisions, edits, and verification evidence an agent needs.

The CLI reference and React Native SDK guide 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:

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:

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:

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.

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:

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:

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

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

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

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:

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:

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:

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.