Documentation Index
Fetch the complete documentation index at: https://docs.newly.app/llms.txt
Use this file to discover all available pages before exploring further.
Native Packages
When building your app, you might see a message saying a native package was detected. This page explains what that means and what to do about it.
What Are Native Packages?
Native packages are libraries that use features built into your phone’s operating system - things like Bluetooth, push notifications, NFC, or health data. These features don’t exist in a web browser, which means they can’t run in the web preview or Expo Go. Examples of native packages include:| Category | Packages |
|---|---|
| Push notifications | onesignal-expo-plugin |
| Bluetooth / NFC | react-native-ble-plx, react-native-nfc-manager |
| Health | react-native-health, react-native-health-connect |
| Camera (advanced) | react-native-vision-camera |
| Maps (Mapbox) | @rnmapbox/maps |
| Storage | react-native-mmkv |
| Firebase | @react-native-firebase/* |
| In-App Purchases | react-native-iap |
| Speech recognition | expo-speech-recognition |
Many common packages do work in Expo Go and web preview - including
expo-camera, react-native-maps, react-native-reanimated, @stripe/stripe-react-native, and most expo-* packages. These come pre-installed in the Expo Go runtime, so they work without a custom build. You’ll only see the native package warning for packages that aren’t pre-installed and use their own native code.What Should I Do?
If your app uses a native package, you need to build for a native simulator instead of using the web preview. Switch to the iOS or Android tab in the preview panel, then follow the steps in our simulator build guide to get your app running.Why Can’t Native Packages Run in Web Preview?
Native packages include platform-specific code written in programming languages like Swift or Kotlin (the languages used to build iPhone and Android apps). This code needs to be baked directly into the app when it’s built. Native packages can also require special device permissions, like Bluetooth or camera access, which need to be set up when the app is built. Expo Go is a pre-built app that Expo provides for quick testing. It comes with a fixed set of native modules already baked into it. When your JavaScript code tries to use a native package that isn’t part of that set, it’s trying to talk to native code that simply doesn’t exist in the app - so it fails or gets stuck. Web preview has the same problem but for a different reason. It runs your app in a browser, and browsers can’t run Swift or Kotlin code at all. A simulator build solves both of these issues. It creates your own custom version of the app with exactly the native packages your project needs compiled into it, so everything runs properly.Still Have Questions?
- Ask the AI in your project chat - describe the issue and it can help debug
- Email us at support@newly.app