One Logo Pool Ball
wwwwwwwwwwwwwwwwwww

Native Setup

Install One Native and generate its iOS and Android projects

For desktop apps, see Native macOS and Linux.

One Native is included in the one package. There is no separate native UI package to install. One v2 uses React 19.3.0 and React Native 0.88; the current examples use 0.88.0. Native components require the New Architecture. The installation guide lists the full dependency set, including screens, Worklets, and Liquid Glass. The iOS deployment floor is 17. See the platform notes for feature-specific requirements.

For a new app, start with:

Terminal window
npx one

For an existing One app, update one to v2 and align its React, React Native, and React Navigation peers. Use your package manager to inspect the installed package’s peer dependencies. The navigation peers are 8 alpha versions, so keep their versions aligned.

Configure the app

Configure the application through native.app in vite.config.ts:

import { one } from 'one/vite'
import { defineConfig } from 'vite'
export default defineConfig({
plugins: [
one({
native: {
app: {
name: 'MyApp',
ios: {
bundleId: 'com.example.myapp',
deploymentTarget: '17.0',
},
android: {
applicationId: 'com.example.myapp',
},
},
},
}),
],
})

Add react-native.config.cjs at the app root:

module.exports = require('one/react-native-config')

For an existing app, install the community native template as a development dependency. One supplies the CLI and platform build tools:

Terminal window
npm install --save-dev @react-native-community/template@0.88.0

Then generate the projects from the app directory:

Terminal window
one prebuild

One generates ios/ and android/ from the React Native community templates. React Native autolinking includes One’s pod, Android module, Fabric components, and native service dependencies. Run this through the app’s scripts or your package manager’s local executable command if one is not on your shell PATH.

Use native.app for icons, launch screens, fonts, deep links, and permissions. The native project guide lists the manifest fields. Give each permission a description of why your app needs it. For example, native.app.imagePicker.camera supplies the camera usage configuration. Updating native configuration or adding a native dependency requires generating and rebuilding the native project.

One’s native startup installs the ES2023 array methods toSorted, toReversed, toSpliced, and with before app modules load. This includes Hermes releases whose built-in array methods are incomplete. Apps use the standard methods directly; dependency code and app startup need no separate polyfill setup.

Apps that keep Expo prebuild follow Coming from Expo.

Precompiled iOS libraries

During pod install, One automatically downloads compatible native libraries from its public GitHub releases when they are available. The binaries cover arm64 iOS devices and Apple Silicon simulators in both Debug and Release. They match One’s native sources, React Native, Nitro and Worklets sources, and the exact Xcode and Swift compiler. Changing any of these inputs selects a different artifact. An unpublished combination compiles from source. Download and checksum errors stop installation.

React Native’s own precompiled core remains enabled by its upstream default. Apps that modify React Native must keep their source-build setting; One does not override it. One uses binaries only when React Native actually resolved its standard precompiled core and dependencies. App-specific Swift packages, SDK bindings and native modules still compile in the app. A binary matches only the exact Release feature-group selection it was built for, so an app with a smaller link set keeps compiling its smaller set from source unless its selection is published.

The installer requires Node 22.18 or newer. To require a matching binary, use ONE_PREBUILT_IOS=1 pod install. To compile One from source, use ONE_PREBUILT_IOS=0 pod install. After changing architectures, dependencies or native inputs, run pod install again. Public GitHub builds publish the complete feature catalog for the supported dependency and Xcode combination; other combinations use source builds. The native artifact format is versioned; packaging changes must advance its format before publishing different bytes.

Run the app

Start One’s development server in one terminal:

Terminal window
one dev

Build and launch the generated app in another:

Terminal window
one run:ios

Or use one run:android. iOS builds need macOS, Xcode, and CocoaPods. Android builds need the Android SDK and JDK 17. Run native compilation on your build machine or CI as appropriate for your project.

One bundles native apps with Rolldown, the same bundler as web.

ONE_PUBLIC_ variables are exposed to app code; see Environment. Rebuild the native app for native code or manifest changes, even when JavaScript hot reload is working.

Add a first native control

Put this in an iOS route, such as app/settings.ios.tsx:

import { useState } from 'react'
import { One } from 'one'
export default function Settings() {
const [enabled, setEnabled] = useState(true)
return (
<One.iOS.Form style={{ flex: 1 }}>
<One.iOS.Section title="Notifications">
<One.iOS.Toggle
label="Allow notifications"
isOn={enabled}
onIsOnChange={setEnabled}
/>
</One.iOS.Section>
</One.iOS.Form>
)
}

The callback updates the controlled setting in React state. For shared native text-input state, use useNativeState with TextInput. This sample changes a setting only; requesting notification permission is a separate Notifications API call.

Edit this page on GitHub.