Build or Run the Native iOS App

Run your iOS app in development with custom dependencies, or build it for App Store and TestFlight

This guide explains how to build and upload your iOS app to the App Store or TestFlight, or run it locally during development with custom native dependencies.

You'll use the prebuild command to generate the native code and Xcode project for iOS, open it with Xcode, and either run the app or archive it for distribution.

Note: If you just want to run your iOS app in development mode without any custom native dependencies, you don't need this guide. All you need is an iOS device with Expo Go installed. It should auto-detect from your simulator, or press q, r in your terminal which is running the One dev server and follow the instructions to open the app in Expo Go.

Prebuild

Before you can run or build your iOS app, you'll need to generate the native code and Xcode project for iOS.

First, ensure the prebuild:native script is defined in your package.json:

{
  "scripts": {
    "prebuild:native": "one prebuild"
  }
 }

Next, run the following command in your terminal:

yarn
npm
bun
pnpm
npm run prebuild:native

This command may prompt you with some questions and could take a few minutes to install CocoaPods dependencies on it's first run.

Once finished, your iOS project will be available in the ./ios directory and ready for use.

Running the App in Development

To run the app, open the .xcworkspace file in the ./ios directory. The filename will vary based on your app's name, but you can generally open it by running this command:

Terminal
open ios/*.xcworkspace

Once Xcode opens, ➊ choose a simulator or physical device, and ➋ click the run button to build and launch the app.

Building for Production

Open the .xcworkspace file from the ios directory. You can do this by running the following command:

Terminal
open ios/*.xcworkspace

Once Xcode opens, follow these steps:

• ➊ Click your app project in the Project Navigator.
• ➋ Under “TARGETS,” select your app.
• ➌ Go to the “Signing & Capabilities” tab.
• ➍ Ensure “Automatically manage signing” is checked.
• ➎ Select a development team.

Once code signing is set up, click "Product" → "Archive" on the menu bar to start the Archive process.

After the archive process completes, Xcode will automatically open the Organizer window with your build. From there, click "Distribute App" to upload the app to the App Store or TestFlight.

Project Setup

You should add a react-native.config.cjs file in your project root to configure React Native to use Vite as the JS bundler during the native build process:

module.exports = {
  commands: [...require('vxrn/react-native-commands')]
}

By doing so, the react-native build command will be overwritten to use Vite as the JS bundler instead of Metro.

If you're using Expo Prebuild, you should also add "vxrn/expo-plugin" in your app config (app.json/app.config.js/app.config.ts):

{
  "expo": {
    "plugins": ["vxrn/expo-plugin"]
  }
}

Troubleshooting

Try cd ios && pod install && cd ...

This often comes with Node found at: /private/var/folders/.../T/xfs-.../node and then /private/var/folders/.../T/xfs-.../node: No such file or directory.

Try to delete ios/.xcode.env.local.

1. Make sure there's a react-native.config.cjs in your project which contains something like this:

   module.exports = {
     commands: [...require('vxrn/react-native-commands')]
   }
   

2. Make sure you have vxrn/expo-plugin included in your app.json (or .js, etc.):

   {
     "expo": {
       "plugins": ["vxrn/expo-plugin"]
     }
   }
   

3. Try to delete the ios directory and run prebuild again.