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.
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:
yarn prebuild:nativeThis 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.
one run:iosThe simplest way to run your app after prebuild is using the CLI:
one run:iosThis will build and launch the app on your default iOS simulator. For Android, use one run:android.
one dev) before launching the native app so it can connect to the bundler.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:
open ios/*.xcworkspaceOnce Xcode opens, ➊ choose a simulator or physical device, and ➋ click the run button to build and launch the app.

Open the .xcworkspace file from the ios directory. You can do this by running the following command:
open ios/*.xcworkspaceOnce Xcode opens, follow these steps:

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.

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:
# macOS: any Docker daemon works; Colima is the lightestbrew install colima dockercolima start
# Linuxsudo apt-get install qemu-userSee 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:
engine option applies to iOS. Android uses One prebuild.new Function and eval, runs in the interpreter without the speedup.one-basic example).Remove engine: 'bun' and prebuild again to go back to Hermes.
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.
npx one.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.
@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.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:
orientation: portrait, landscape or default (all four). Unset keeps a
portrait-only phone.userInterfaceStyle: light or dark locks the appearance; automatic,
like unset, follows the system.splash.resizeMode: cover fills the iOS launch screen with untrimmed
artwork; contain (the default) centers it at width.splash.dark: backgroundColor, and optionally source and
backgroundImage, for a launch in dark appearance.splash.backgroundImage: a full-bleed image, such as a gradient, under the
artwork on the launch screen: iOS aspect-fills it, Android stretches it to
fill (a gradient renders the same either way). Android’s system splash
itself shows only the color and icon.One.LaunchScreen.preventAutoHide() while
modules evaluate and One.LaunchScreen.hide({ fade: true }) when ready.notifications.apsEnvironment: production for a build signed for
TestFlight or the App Store; push uses development otherwise.ios.accentColor: { light, dark } hex colors for the app’s tint (tab
selection, text cursor, system controls), read in JS as
PlatformColor('AccentColor').ios.assetCatalog: a project-relative .xcassets folder, in the format Xcode
writes, whose imagesets, colorsets and symbolsets prebuild merges into the
app’s asset catalog, for UIImage(named:) and a tab’s image. A name
prebuild generates itself, such as AppIcon or AccentColor, is an error.fonts: project-relative .ttf or .otf files bundled into the app. iOS
lists them in UIAppFonts; Android loads them from assets/fonts. Use the
font’s own family name in styles.android.adaptiveIcon: foreground, then background (an image) or
backgroundColor, and an optional monochrome layer for Android 13 themed
icons. The foreground is a 108 dp square with the artwork inside the central
66 dp.ios.associatedDomains (such as applinks:example.com) and
android.appLinks ({ host, pathPrefix }, verified with autoVerify) route
https links into the app.ios.usesAppleSignIn adds the Sign in with Apple entitlement.android.permissions adds manifest permissions (a bare name means
android.permission.<name>); android.blockedPermissions removes ones a
library merges in.android.targetSdk and android.compileSdk set the Gradle SDK levels.ios.googleServicesFile and android.googleServicesFile bundle a Firebase
GoogleService-Info.plist and google-services.json; Android also gets the
google-services Gradle plugin. For Google Sign-In, add the plist’s
REVERSED_CLIENT_ID to scheme.android.minify runs R8 on release builds, android.shrinkResources (which
needs minify) drops unused resources, and android.proguardRules appends
keep rules to proguard-rules.pro.ios.infoPlist and ios.entitlements add keys native.app does not model,
such as NSUserTrackingUsageDescription. A key the template or another field
already writes fails prebuild; set it through that field.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.
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.
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)}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:
# ⬇️ Add this line directly above the line that calls react-native-xcode.shexport 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'"`
ios/*.xcworkspace isn’t thereTry cd ios && pod install && cd ...
node: No such file or directory during Xcode buildThis 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.
No Metro config foundMake sure there’s a react-native.config.cjs in your project which contains something like this:
module.exports = require('one/react-native-config')Confirm native.app.ios.bundleId is set in vite.config.ts.
Delete the generated ios directory and run one prebuild again.
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.