React Native
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:
| Step | Nothing cached yet | Packages cached |
|---|---|---|
| Fresh machine ready | 19s | 19s |
| npm ci (953 packages) | 39s | 7s |
| pod install (65 dependencies) | 59s | 58s |
| xcodebuild, Release, Hermes | 2m 10s | 2m 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
| Tool | Version |
|---|---|
| Node | 24.22.2 |
| npm | 11.19.1 |
| Yarn | 1.22.22 |
| pnpm | installed |
| Xcode | 27.2 |
| CocoaPods | 1.17.0 |
| Ruby | 4.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
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
| Symptom | Cause |
|---|---|
| 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.