Build the Vibra Code iOS and Android app from source

The Vibra Code mobile app is a heavily modified fork of Expo Go. It includes a native iOS chat UI built with Texture and IGListKit, along with all the Vibra Code screens and services. This guide covers building and running it from source.

macOS is required for iOS builds. You cannot build the iOS app on Linux or Windows. Android builds can be done on any platform.

Prerequisites

macOS with Xcode 16 or later
CocoaPods: gem install cocoapods
Yarn: npm install -g yarn
cmake and ninja (for building the Hermes JS engine):

brew bundle

Running brew bundle from the vibracode-mobile root installs cmake, ninja, and other native build dependencies declared in the Brewfile.

Setup

Clone the repository

The mobile app depends on submodules — React Native is built from source and the Expo template is included as a submodule. You must use --recurse-submodules.

git clone --recurse-submodules https://github.com/sa4hnd/vibra-code.git
cd vibra-code/vibracode-mobile

Install JavaScript dependencies

yarn install

Run native setup

This script configures native build settings and prepares the workspace:

yarn setup:native

Build Expo packages

The project uses a local copy of the Expo SDK. Build it from source:

cd packages/expo && yarn build && cd ../..

Install React Native from source

cd react-native-lab/react-native && yarn install && cd ../..

Install CocoaPods

cd apps/expo-go/ios && pod install && cd ../../..

Configure the mobile environment

Copy the example env file and fill in your values:

cp apps/expo-go/.env.example apps/expo-go/.env

At minimum you need:

EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=
EXPO_PUBLIC_CONVEX_URL=
EXPO_PUBLIC_V0_API_URL=http://localhost:3000

Set EXPO_PUBLIC_V0_API_URL and EXPO_PUBLIC_API_URL to the URL of your running backend. Use http://localhost:3000 for local development.

Start Metro

Metro must run on port 80 for the local Expo Go kernel to find it:

cd apps/expo-go && yarn start

Metro must be running on port 80 before you build in Xcode. If Metro is on any other port, the app will not connect to your local bundle.

Build and run in Xcode

Open apps/expo-go/ios/Exponent.xcworkspace in Xcode (use .xcworkspace, not .xcodeproj)
Open EXBuildConstants.plist and set DEV_KERNEL_SOURCE to LOCAL
Select your target device or simulator
Press Build and Run (⌘R)

Android build

Android builds work on macOS, Linux, or Windows:

cd apps/expo-go/android && ./gradlew app:assembleDebug

The resulting APK is in android/app/build/outputs/apk/debug/.

Troubleshooting

Problem	Fix
SHA-1 errors or symlink errors during build	`rm -rf ./react-native-lab/react-native/node_modules` then re-run `yarn install` in that directory
C++ build errors (`.cxx` directory issues)	`find . -name ".cxx" -type d -prune -exec rm -rf '{}' +` then rebuild
Everything broken after a rebase or submodule change	`git submodule foreach --recursive git clean -xfd` then re-run all setup steps from `yarn install`

Project structure

The key directories inside vibracode-mobile/apps/expo-go/ are:

apps/expo-go/
├── src/screens/         # Vibra Code screens (VibraCreateAppScreen, etc.)
├── src/services/        # Session, notification, and RevenueCat services
├── src/navigation/      # App navigation (Home, Create, Profile tabs)
├── ios/Client/Menu/     # Native iOS chat UI (Texture + IGListKit)
└── convex/              # Symlink to vibracode-backend/convex (shared schema)

The native chat UI in ios/Client/Menu/ is written in Objective-C and uses Texture (AsyncDisplayKit) for off-main-thread rendering.

Next steps

Backend setup — make sure the backend is running before you connect the app
Environment variables reference — full list of mobile env vars

Deployment

Customization

Contributing

Build the Vibra Code iOS and Android app from source

Prerequisites

Setup

Android build

Troubleshooting

Project structure

Next steps

​Prerequisites

​Setup

​Android build

​Troubleshooting

​Project structure

​Next steps

Prerequisites

Setup

Android build

Troubleshooting

Project structure

Next steps