One Logo Pool Ball
wwwwwwwwwwwwwwwwwww

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.

one prebuild generates the Xcode project from native.app in vite.config.ts, and one run:ios launches it on a simulator. Apps that keep Expo prebuild follow Coming from Expo.

Prerequisites: To build and run the iOS app, you’ll need a Mac with Xcode installed. To upload the app to the App Store or TestFlight, you’ll additionally need a paid Apple Developer account.
If you are starting with an existing React Native project without using one of our templates, please follow the instructions in the Project Setup section to configure your project first.

Prebuild

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

Ensure the prebuild:native script is defined in your package.json:

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

Then run:

Terminal window
yarn prebuild:native

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

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

Running the App in Development

Using one run:ios

The simplest way to run your app after prebuild is using the CLI:

Terminal window
one run:ios

This will build and launch the app on your default iOS simulator. For Android, use one run:android.

Make sure the One dev server is running (one dev) before launching the native app so it can connect to the bundler.

Using Xcode

Alternatively, you can 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 window
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 window
open ios/*.xcworkspace

Once Xcode opens, follow these steps:

You need a paid Apple Developer Program account to upload apps to the App Store or TestFlight. If you’re not signed into your Apple Developer account in Xcode, select “Add an Account…” from the dropdown to log in.
If you encounter any other problems, try to follow the instructions that Xcode give you to fix them.

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.

You can also open the Organizer window by clicking “Window” → “Organizer” on the menu bar.

Bun engine (experimental)

Release builds can run on Bun’s ahead-of-time compiler instead of Hermes. The release bundle is compiled into machine code at build time, inside Bun’s fork of JavaScriptCore, and shipped in the signed app. Development builds keep Hermes and fast refresh.

one({
native: {
app: {
ios: { bundleId: 'com.example.app', engine: 'bun' },
},
},
})

Apps on expo prebuild pass the same option to the plugin: ['vxrn/expo-plugin', { engine: 'bun' }].

One prebuild also supports Android Release builds with android: { applicationId: 'com.example.app', engine: 'bun' }. Android requires ARM64 and API 28 or newer. Gradle downloads the Android engine from a pinned onejs/bun-engine release into the user cache (~/Library/Caches/one/bun-engine on macOS, ~/.cache/one/bun-engine on Linux), checks its checksum, and reuses it after that. Set ONE_BUN_ENGINE_DIR to a local Android engine build with android/arm64-v8a/libbun.so, android/include/JavaScriptCore, and android/compile instead. The compiler and runtime must match their Bun revision, built-in modules and JavaScriptCore layout, so the iOS download’s macOS compiler cannot compile for the Android runtime.

The Android build compiles index.android.bundle into libbun.so and installs a JNI runtime factory. Debug builds use Hermes.

Android Release builds compile the bundle with Bun’s Android compiler, which ships in the engine package and runs on the build machine, so builds need no emulator or phone. It needs Python 3 and a way to run an Android ARM64 program:

Terminal window
# macOS: any Docker daemon works; Colima is the lightest
brew install colima docker
colima start
# Linux
sudo apt-get install qemu-user

See the Android compiler packaging guide when preparing a local engine build.

pod install downloads the engine from a pinned onejs/bun-engine release into ~/Library/Caches/one/bun-engine, checks its checksum, and reuses it after that. Set ONE_BUN_ENGINE_DIR to use a local engine build instead. The app executable links the runtime statically, so no Bun framework loads before main. The bundle phase compiles main.jsbundle on every Release build and the link places the program in the executable’s __TEXT segment, since an App Store binary may have only one executable segment.

Limits:

Remove engine: 'bun' and prebuild again to go back to Hermes.

View culling

viewCulling: true turns on React Native’s view culling. Views outside a scroll view’s visible area stay unmounted, where React Native otherwise mounts them and walks every view under the scroll view after each update to clip them. Long lists and feeds spend less time on the main thread, with either engine.

one({
native: {
app: {
ios: { bundleId: 'com.example.app', viewCulling: true },
},
},
})

Apps on expo prebuild pass ['vxrn/expo-plugin', { viewCulling: true }]. React Native still marks view culling experimental, so check views that draw outside their bounds, such as shadows and overflowing children, inside scroll views.

Project Setup

We’ve set this up in most project templates, so you can skip this section if you’ve created your project with npx one.

React Native

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 = require('one/react-native-config')

This routes native build bundling through One and links One’s native SwiftUI, Compose, effects, and safe area implementation through community autolinking.

If you are using React Native 0.74.x or below, we rely on a patch to the @react-native-community/cli package to make this work. For the patch to apply, you’ll need to start the dev server at least once.

One Prebuild

Configure the native application in vite.config.ts, then generate the React Native community projects with one prebuild:

one({
native: {
app: {
name: 'MyApp',
icon: {
source: './public/app-icon.png',
backgroundColor: '#000000',
},
splash: {
source: './public/splash.png',
backgroundColor: '#000000',
width: 200,
},
ios: {
bundleId: 'com.example.myapp',
usesNonExemptEncryption: false,
fileSharing: true,
},
android: { applicationId: 'com.example.myapp' },
imagePicker: {
camera: 'Take profile photos.',
},
},
},
})

One reads this manifest directly. It generates the iOS and Android app icons and launch screens from the shared sources. imagePicker.camera is the iOS camera usage description; prebuild writes it to NSCameraUsageDescription and declares the Android camera permission, both required for One.ImagePicker.launchCamera. The icon must be a square image at least 1024 pixels wide. Splash artwork is centered at width points on iOS and density-independent pixels on Android. One removes a solid outer border matching backgroundColor before sizing the artwork, then generates density-specific Android assets inside a 288 dp square. The launch screen stays up until React Native draws its first content, so it never gives way to an empty root.

ios.fileSharing sets UIFileSharingEnabled plus LSSupportsOpeningDocumentsInPlace in the generated Info.plist. The user sees the app’s Documents as a folder in the Files app and in document pickers under On My iPhone, and files the app saves there can be opened in place.

The rest of native.app covers appearance, links, and store settings:

iOS widgets and Live Activities

Set ios.widgets to have one prebuild --platform ios generate a WidgetKit extension, App Group entitlements for both targets, and a small SwiftUI widget and Live Activity. The app writes a typed payload to the App Group. The extension reads that payload without running the app’s JavaScript.

ios: {
bundleId: 'com.example.myapp',
deploymentTarget: '17.0',
widgets: {
appGroup: 'group.com.example.myapp',
kind: 'MyAppStatus',
displayName: 'My status',
description: 'Shows the latest status.',
families: [
'systemSmall',
'systemMedium',
'accessoryCircular',
'accessoryRectangular',
'accessoryInline',
],
},
}
import { One } from 'one'
await One.Widgets.write({ title: 'Order', value: '2 of 3', subtitle: 'On the way' })
const id = await One.LiveActivities.start('Order', { status: 'Preparing', value: '1 of 3' })
await One.LiveActivities.update(id, { status: 'On the way', value: '2 of 3' })
const token = await One.LiveActivities.pushToken(id)
const unsubscribe = One.LiveActivities.onPushToken(({ id, token }) => {
// send the ActivityKit token to your server
})
await One.LiveActivities.end(id)
unsubscribe()

Pass true as the third argument to start to request an ActivityKit push token. Set ios.widgets.pushNotifications: true before prebuild to add the APNs entitlement; the signing profile must also enable Push Notifications. If notifications.push is already enabled, One includes that entitlement in the same app entitlement file as the widget’s App Group. pushToken returns the current token or null while iOS has not issued one; onPushToken reports later token changes. These APIs are separate from notification permissions and device tokens. App Groups and Live Activities need the corresponding capabilities in the app’s signing profile on a physical device.

One also accepts JSX layouts through One.iOS.WidgetUI. The app serializes the layout to the same typed App Group contract or ActivityKit state. The generated SwiftUI extension renders it without a JavaScript runtime or an extra package.

import { One } from 'one'
const W = One.iOS.WidgetUI
function OrderStatus({ progress, step }: { progress: string; step: number }) {
return (
<W.VStack style={{ padding: 12, spacing: 8 }}>
<W.HStack>
<W.Image systemName="shippingbox.fill" style={{ color: '#1685B1' }} />
<W.Text style={{ fontSize: 18, fontWeight: 'bold' }}>Order</W.Text>
</W.HStack>
<W.Text>{progress}</W.Text>
<W.Progress value={step} total={3} style={{ color: '#1685B1' }} />
</W.VStack>
)
}
await One.Widgets.writeView(<OrderStatus progress="2 of 3" step={2} />)
const id = await One.LiveActivities.startView('Order', {
lockScreen: <OrderStatus progress="1 of 3" step={1} />,
compactLeading: <W.Text>Order</W.Text>,
compactTrailing: <W.Text>1/3</W.Text>,
expandedBottom: <OrderStatus progress="1 of 3" step={1} />,
})
await One.LiveActivities.updateView(id, {
lockScreen: <OrderStatus progress="2 of 3" step={2} />,
compactLeading: <W.Text>Order</W.Text>,
compactTrailing: <W.Text>2/3</W.Text>,
expandedBottom: <OrderStatus progress="2 of 3" step={2} />,
})
await One.LiveActivities.end(id)

The activity view also accepts expandedLeading, expandedTrailing, and expandedBottom for the expanded Dynamic Island. The compact slots and minimal cover its other presentations.

WidgetUI supports Text, Image (SF Symbols), VStack, HStack, ZStack, Spacer, Divider, Progress, Gauge, Circle, Rectangle, RoundedRectangle, Link, and Button. Styles include color, background color, font size, weight and design, padding, corner radius, spacing, size, opacity, line limit, and alignment. Colors use six-digit hex values. JSX layouts can contain pure function components; compute hook state in the app and pass it as props. The write and writeView methods update the same widget.

W.Button dispatches an interactive AppIntent (OneWidgetButtonIntent) from a Home Screen widget or Live Activity without foregrounding the app, queuing an action in the App Group that the app claims with One.Widgets.claimActions() or observes live with One.Widgets.onAction(listener):

<W.Button action="toggle-playback" value="track-42">
<W.HStack style={{ padding: 8, backgroundColor: '#1685B1', borderRadius: 8 }}>
<W.Image systemName="play.fill" style={{ color: '#FFFFFF' }} />
<W.Text style={{ color: '#FFFFFF', fontWeight: 'semibold' }}>Play</W.Text>
</W.HStack>
</W.Button>
const pending = await One.Widgets.claimActions()
const unsubscribe = One.Widgets.onAction(({ id, action, value, timestampMs }) => {
// handle interactive widget or Live Activity button tap
})

Android widgets require a separate Glance target, storage contract, and lifecycle; this setting generates only iOS targets.

Siri and App Intents

Set ios.appIntents.actions to generate an AppIntent per action and register AppShortcutsProvider phrases for Siri, the Shortcuts app, Spotlight, and Action Button:

ios: {
bundleId: 'com.example.myapp',
appIntents: {
actions: [
{
id: 'log-water',
title: 'Log Water',
description: 'Record water intake and speak a summary.',
textParameterTitle: 'Amount',
shortcutPhrase: 'Log water in {app}',
shortcutPhrases: ['Add water in {app}'],
systemImageName: 'drop.fill',
openAppWhenRun: false,
},
],
},
}

Register each handler at module scope in setupFile.native:

import { One } from 'one'
One.AppIntents.defineAction('log-water', async (text) => {
return `Logged ${text || '250ml'}.`
})

Each generated AppIntent conforms to ProvidesDialog and returns the handler’s string as spoken and visual Siri dialog output.

Share Extension Drafts

When an iOS Share Extension persists submissions into your App Group with OneShareTargetDraftStore, read and discard queued drafts in the main app with One.ShareTarget:

import { One } from 'one'
const drafts = await One.ShareTarget.getDrafts('group.com.example.myapp')
for (const draft of drafts) {
await One.ShareTarget.discardDraft('group.com.example.myapp', draft.id)
}

iOS Project Setup

one prebuild applies this configuration to generated projects. Follow the manual step only for an existing native project that One did not generate.

In the “Bundle React Native code and images” phase, make the following change in the shell script:

Terminal window
# ⬇️ Add this line directly above the line that calls react-native-xcode.sh
export CLI_PATH="$("$NODE_BINARY" --print "require('path').dirname(require.resolve('react-native/package.json')) + '/cli.js'")"
`"$NODE_BINARY" --print "require('path').dirname(require.resolve('react-native/package.json')) + '/scripts/react-native-xcode.sh'"`

Troubleshooting

ios/*.xcworkspace isn’t there

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

Error: node: No such file or directory during Xcode build

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.

Error: No Metro config found

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

    module.exports = require('one/react-native-config')
  2. Confirm native.app.ios.bundleId is set in vite.config.ts.

  3. Delete the generated ios directory and run one prebuild again.

App Transport Security

Set native.app.ios.appTransportSecurity to replace the community template’s NSAppTransportSecurity dictionary. For an app that must connect to arbitrary HTTP endpoints, use { NSAllowsArbitraryLoads: true }. The replacement removes the template’s local-networking exception, which otherwise changes how iOS interprets arbitrary loads. Use this field rather than setting the same key in ios.infoPlist.

Edit this page on GitHub.