Guides

React Native

Last updated 14 September 2026

Node, npm, CocoaPods and Xcode are all installed and on the path. A React Native iOS release build needs nothing installed on the machine first.

Real numbers from builds on our hardware — a new React Native 0.76.5 app, 953 packages, from nothing to a compiled release binary. Packages come from a cache on our build network, so the first column is a project whose dependencies we have never fetched before, and the second is the same build once they are cached:

StepNothing cached yetPackages cached
Fresh machine ready 19s19s
npm ci (953 packages) 39s7s
pod install (65 dependencies) 59s58s
xcodebuild, Release, Hermes 2m 10s2m 13s
Whole build (the steps above added up) 4m 07s 3m 38s

Commit your lockfile. Without one, npm install has to ask the registry about every package before it can work out the tree, and that is by far the slowest thing a React Native build does: in the same build where npm ci took 6s, npm install took 4m 35s.

01What is already on the machine

ToolVersion
Node24.22.2
npm11.19.1
Yarn1.22.22
pnpminstalled
Xcode27.2
CocoaPods1.17.0
Ruby4.0.7 via rbenv — no sudo gem install needed
JDK 17 + Android SDK installed, so you can build Android in the same run

These are the versions on the default image. To stay on Xcode 26.6, add one line to your build config — see image.

Yarn and pnpm are both installed. If your packageManager field pins a specific pnpm or Yarn version, make corepack enable your first step. Corepack 0.36 ships with the Node on the machine, and it will fetch the version that field asks for.

npm downloads from the public registry. npm ci with a lockfile is the fastest and most repeatable way to install.

If you install private packages from npmjs.com with a token in your project's .npmrc, add registry=https://registry.npmjs.org/ to that same file. The cache never receives your token, so private packages would otherwise fail with a 404.

02The whole file

script:
  - npm ci
  - cd ios && pod install && cd ..
  - xcodebuild \
      -workspace ios/MyApp.xcworkspace \
      -scheme MyApp \
      -configuration Release \
      -destination "generic/platform=iOS" \
      -derivedDataPath ios/build \
      CODE_SIGNING_ALLOWED=NO \
      -quiet \
      build
Use npm ci, not npm install. It installs exactly what package-lock.json says and fails loudly if the lockfile and package.json disagree — which is the single most common reason a React Native build is green on a laptop and red on a build machine.

03Keep -quiet on

A React Native build compiles Hermes, Folly, boost, glog and about sixty other pods, and each one is happy to tell you about it. Without -quiet a single build can approach the 20 MB log limit on its own, and the failure you care about ends up buried in thousands of lines of warnings you cannot act on.

The React Native template itself produces a run-script warning on every build (“will be run during every build because it does not specify any outputs”). That is upstream's, not yours and not ours, and it is safe to ignore.

04Commit both lockfiles

package-lock.json and ios/Podfile.lock. React Native pins its native dependencies through the JavaScript ones, so a drifting package-lock.json silently changes which pods get installed — and the resulting failure looks like an Xcode problem, not a dependency one.

If pod install complains that the lockfile is out of date, regenerate it on your machine and commit it. Do not “fix” it in the build with pod update; that just means every build resolves differently.

05Tests

script:
  - npm ci
  - npm test -- --reporters=default --reporters=jest-junit || true

env:
  JEST_JUNIT_OUTPUT_DIR: reports
  JEST_JUNIT_OUTPUT_NAME: jest.xml

tests:
  - reports/jest.xml

Add jest-junit as a dev dependency. As everywhere else, the || true is there so a failing test does not stop the build before the report is written — the parsed report is what turns the build red, and it names the test.

06Android in the same run

script:
  - npm ci
  - cd android && ./gradlew assembleRelease && cd ..
  - cd ios && pod install && cd ..
  - xcodebuild ... -quiet build

artifacts:
  - android/app/build/outputs/apk/release/*.apk

One machine, both platforms, one bill.

07Producing a signed .ipa

Store your certificate and profile in Secrets first — see code signing & TestFlight:

signing:
  certificate: APPLE_DIST_CERT
  profile: MyApp_AppStore

script:
  - npm ci
  - cd ios && pod install && cd ..
  - xcodebuild \
      -workspace ios/MyApp.xcworkspace -scheme MyApp \
      -configuration Release \
      -destination "generic/platform=iOS" \
      -archivePath build/MyApp.xcarchive \
      CODE_SIGNING_ALLOWED=NO CODE_SIGNING_REQUIRED=NO CODE_SIGN_IDENTITY="" \
      -quiet \
      archive
  - xcodebuild -exportArchive \
      -archivePath build/MyApp.xcarchive \
      -exportOptionsPlist ios/ExportOptions.plist \
      -exportPath build/ipa

artifacts:
  - build/ipa/*.ipa

08Things that trip people up

SymptomCause
Command PhaseScriptExecution failed in the bundle step The Metro bundler could not find a module. Almost always a dependency that is in node_modules on your laptop but not in package.json.
No podspec found for ... pod install ran before npm ci. The pods are generated from the JavaScript packages, so the order matters.
Hermes takes minutes on every build Expected on a fresh machine — there is no shared cache between builds, by design. It was 2m 14s in the run above, for the whole native compile.
error: unable to open configuration settings file You built the .xcodeproj instead of the .xcworkspace. CocoaPods projects must be built through the workspace.
A native module needs an env var at build time Put non-secret values in env, and anything sensitive in Secrets — never in script, which appears in your log.

Next: code signing & TestFlight, or the full configuration reference.


Something here wrong or missing? Tell us — we read every message, and documentation fixes go out the same day.