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:
npx oneFor 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 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:
npm install --save-dev @react-native-community/template@0.88.0Then generate the projects from the app directory:
one prebuildOne 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.
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.
Start One’s development server in one terminal:
one devBuild and launch the generated app in another:
one run:iosOr 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.
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.