Connect an existing Expo app to Mach, declare the Expo build pipeline, and run your first cloud build.
Before you start
This guide is for an existing Expo project that is configured through app.json, app.config.js, or app.config.ts. Mach uses Expo prebuild during its cloud build pipeline, then takes care of signing, native versioning, artifact upload, and optional store submission.
You need Node.js, a Mach account, and the app identifiers you intend to ship: an iOS bundle identifier and an Android package name. You can connect signing credentials after the project is linked.
Use framework: expo when Expo prebuild owns or refreshes native configuration.
Use framework: react-native instead if your Expo project commits native folders and you deliberately do not want prebuild to regenerate them.
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 Expo project
From the root of the Expo project, run mach link. Select the Mach project you want to connect. The command writes the project identity into mach.config.json without changing your application source files.
One config file, one source of truth
Keep mach.config.json at the repository root. For a workspace app, point appDirectory at the mobile app folder instead of duplicating configuration.
3. Declare the Expo pipeline
Mach never guesses the framework from package.json. Set framework to expo explicitly, then confirm the identifiers and version counters for the app you are building.
{
"framework": "expo",
"appDirectory": ".",
"ios": {
"bundleIdentifier": "com.example.app",
"buildNumber": "auto"
},
"android": {
"package": "com.example.app",
"versionCode": "auto"
},
"build": {
"development": {
"developmentClient": true,
"distribution": "development",
"environment": "development"
},
"production": {
"distribution": "store"
}
}
}
Version counters stay in Mach
With buildNumber and versionCode set to "auto", Mach allocates the next scoped Dashboard value during a build. Your Expo version remains the public marketing version.
4. Review the resolved configuration
Before spending a build minute, inspect the production profile. This is a useful habit whenever a profile inherits or overrides values.
mach config --profile production
5. Run your first build
Run the platform you are ready to test. For Expo projects, Mach runs Expo prebuild as part of the cloud build, so Expo config plugins and generated native configuration are included before compilation.
mach build --platform ios --profile production
mach build --platform android --profile production
What happens next
Your build appears in the Mach dashboard with logs, artifacts, resolved runtime details, and signing status. Add credentials before a signed release build if they are not already stored for the selected profile.
Use mach credentials to configure signing certificates, profiles, or Android keystores.
Use mach ota setup when you are ready for Mach-hosted over-the-air updates.
Use mach deeplink setup when the app needs Universal Links, App Links, or HTTPS OAuth callbacks.
