Android Guide
- If you have Linux, watchman can be installed via apt on debian/ubuntu. Alternatively you may install it via Homebrew for Linux - recommended by watchman, but may cause other issues on Linux.
iOS Guide
- Make sure you have the latest version of the Xcode command line tools installed: xcode-select --install

NixOS prerequisites

shell

USE_ANDROID=1 nix-shell

flakes

nix develop .#use_android

Before you run the app

Run yarn native:prebuild:clean to generate ios/ and android/ directories.
- You can prebuild for specific platform if you setup only Android/iOS: yarn prebuild:clean --platform [android|ios]
- It's necessary to re-run faster version of this command yarn native:prebuild (shortcut yarn p) on any change in native code (when you change branch/pull/rebase).

Running app on Android

Connect device or run emulator.
- For a physical device, refer to instructions.
  - It's recommended to use adb over wifi because you will have free up a USB port to connect Trezor device.
Run packager - yarn native:start in separate terminal window and keep it running
Run native build - yarn native:android this takes time (~10min) and it should install and start the app at the end
With emulator running, reverse android emulator ports to enable communication between the app and localhost services - yarn native:reverse-ports

Running app on iOS

You need a Mac to be able to run the iOS app.

Trezor can't be connected to iOS device via cable, but it's possible to use Portfolio tracker feature for watch only wallets. You will need Xcode and xcode-select.

Run packager - yarn native:start
Run yarn native:ios to build and run the app on iOS Simulator/device

Or via Xcode (for native errors debug):

Open suite-native/app/ios/TrezorSuite.xcworkspace in Xcode (from cli xed suite-native/app/ios)
Hit the ▶️ Run button

It is also possible for development purposes to connect Trezor emulator to iOS Simulator if you turn on the feature flag Connect device in DEV utils.

Connecting a physical Trezor

Once Trezor Suite is running in iOS Simulator / Android emulator, it's possible to use it with a physical Trezor.

Start desktop version of Trezor Suite that will serve as Trezor Bridge.
- Make sure Trezor emulator is stopped before starting the desktop app.
Connect a physical Trezor to your laptop and unlock it if necessary.
You might need to tap the Use Trezor here button and/or reload the app.

Patience might be required but your Trezor should be connected eventually.

Aliases

You can use shorter versions of previous script commands OR navigate to suite-native/app folder and run scripts from there.

Aliases available in root folder:

yarn s = yarn native:start
yarn p = yarn native:prebuild
yarn ports = yarn native:reverse-ports
yarn a = yarn native:android
yarn ios = yarn native:ios

DEV utils

You can show DEV utils on production build FOR DEVELOPMENT PURPOSES ONLY – do not use it for your personal wallets!

To reveal dev menu, you have to click at least 7 times on commit hash at the bottom of About Trezor Suite page.

Environment variables

How our ENV variables works is describe in Environment variables in Expo documentation.

ENV variables for each Expo profile are defined in eas.json config.

You can override ENV variables locally using .env.development.local (or .env.test.local for tests) files.

If you use .env file, it has the lowest priority. See what other .env* files you can use.

EXPO_PUBLIC_IS_SENTRY_ON_DEBUG_BUILD_ENABLED=true to debug Sentry locally and
EXPO_PUBLIC_IS_NATIVE_USB_LOGGER_ENABLED=true to debug @trezor/transport-native-usb locally.
EXPO_PUBLIC_IS_NATIVE_BLUETOOTH_LOGGER_ENABLED=true to debug @trezor/transport-native-bluetooth locally.
EXPO_PUBLIC_FF_* overrides initial state for Feature Flags. See .env.development for examples to copy to .env.development.local file and featureFlagsSlice.ts for all available values.

Native changes - bumping runtimeVersion

Whenever you do a change in a native code (updating native dependency and so on), you have to bump runtimeVersion in app.config.ts file manually so EAS knows that it has to prepare new development build. See Runtime Versions Expo Docs. Hopefully it's just a temporary situation until fingerprint policy is finalized. Fingerprint policy is not working well with development builds yet, waiting for SDK 52.

Troubleshooting

For any issues with the build, try to clean the project and rebuild it:
- yarn native:prebuild:clean
- yarn native:android or yarn native:ios
In case of issues with the packager, try to restart it with --reset-cache i.e (yarn s --reset-cache).
If metro crashes after running yarn start on iOS, try running watchman watch-del-all to clear stale file‑watch state.
Sometimes it's helpful to combine two previous points with uninstalling the app from the device/emulator.
Make sure you are using pure Node or nvm for managing node version (other version managers like fnm can cause build issues on iOS).
npx react-native doctor may help to identify issues with your environment, though not every check has to pass
Android emulator on Linux may be unstable with default software renderer. Then go to settings of the Android Virtual Device and choose Graphics acceleration: Hardware.
For further debugging, start emulator with adb logcat -v long > emulator_log.txt running somewhere in the background.

README.md Unescape Escape

@suite-native/app

Prerequisites