Connect a bare React Native app to Mach while keeping the native iOS and Android projects you already maintain.
Before you start
This guide is for a vanilla React Native, or React Native CLI, project with committed ios and android folders. Mach builds those native projects directly. It does not run Expo prebuild, replace your native folders, or inject Expo-only build settings.
You need Node.js, a Mach account, a working Android Gradle project, and an iOS workspace or Xcode project for iOS builds. Keep the bundle identifier and package name aligned with the apps you already maintain.
Use framework: react-native when your repository owns native configuration.
Set ios.iosScheme if the iOS project has more than one buildable scheme.
1. Install Mach and sign in
Install the Mach CLI once, then authenticate it with your Mach account.
npm install -g @radhya/mach
mach login
2. Link the React Native project
Run mach link from the repository root and select the corresponding Mach project. It creates or updates mach.config.json with the project identity while leaving your existing native code in place.
cd my-react-native-app
mach link
Native folders remain yours
Mach uses the iOS and Android projects committed to the repository. Keep your CocoaPods, Gradle plugins, Firebase setup, and other native customisations exactly where they already live.
3. Declare the React Native pipeline
Set the framework explicitly and keep the identifiers and build counters in mach.config.json. This prevents a dependency change in package.json from changing how a production build behaves.
{
"framework": "react-native",
"appDirectory": ".",
"ios": {
"bundleIdentifier": "com.example.app",
"iosScheme": "MyApp",
"buildNumber": "auto"
},
"android": {
"package": "com.example.app",
"versionCode": "auto"
},
"build": {
"development": {
"distribution": "development",
"environment": "development"
},
"production": {
"distribution": "store"
}
}
}
Keep auto-versioning predictable
Use "auto" for Android versionCode and iOS buildNumber to let Mach allocate the next Dashboard counter. Use an explicit value only when you intentionally need to seed or control a release train.
4. Review the resolved configuration
Check the profile that will build before you run it. This confirms the target identifiers, distribution mode, and versioning values resolved from the project config.
mach config --profile production
5. Run your first build
Mach installs dependencies, runs CocoaPods for iOS when needed, builds your existing Xcode or Gradle project, then uploads the artifact to the dashboard.
mach build --platform ios --profile production
mach build --platform android --profile production
Optional: prepare OTA updates
Mach OTA is available for bare React Native too. The setup flow can add the Expo Modules and expo-updates pieces required by the open-source runtime while keeping update hosting and release control in Mach. Review and commit the generated native changes before building the OTA-enabled binary.
mach ota setup
mach ota verify
