Native Modules

A “native module” is any React Native package that ships compiled iOS/Android code — anything that pokes at the device’s hardware or OS APIs. These behave differently in the phone-frame preview (which runs React Native Web) than on a real device. This page is the cheat sheet so you don’t waste a 30-minute build finding out.

​

The three buckets

​

When you need a Build & Ship vs OTA

The decisive question: does the package add files under node_modules/.../ios/ or android/?

• Yes → adding or upgrading the package means a Build & Ship. The previous binary doesn’t have the new native code; an OTA can’t deliver it.
• No → it’s pure JS. OTA can deliver the change.

You can check this fast: after npm install <package>, look in node_modules/<package>/. If you see ios/ or android/ directories, it’s native. The Hiveku AI knows this — when you ask it to add expo-camera, it’ll include “you’ll need to Build & Ship after this lands” in its response. If you ask it to add date-fns, it’ll say “OTA is fine.”

​

Common native modules and their preview behavior

​

Hardware access

If you build a “scan my receipt” feature, the preview can’t validate it. Publish to Preview channel and open on a real phone with Expo Go to test.

​

Storage & secrets

The Supabase client in the starter uses expo-secure-store for session persistence on device, and falls back to localStorage on web — so authentication works in both. Custom encryption flows that require hardware-backed crypto (Keychain) won’t actually be hardware-backed in preview.

​

Notifications & background

These only work after a Build & Ship to TestFlight + a real device install. There’s no preview path; OTA can’t deliver them either if not already in the binary.

​

Auth providers

Sign-in with Apple is required by App Store rules if you also offer Google sign-in. Add the entitlement in app.json and Build & Ship — no preview path.

​

UI / animation

Heavy animation testing is best on a real device — the web build’s frame budget is different from native. Layout and basic transitions are fine to validate in preview.

​

Common picks for the v1 starter

The Native Mobile starter ships with:

• react-native, react, expo, expo-router, expo-status-bar, expo-secure-store, expo-splash-screen
• react-native-safe-area-context, react-native-screens, react-native-gesture-handler, react-native-reanimated, react-native-url-polyfill
• nativewind + tailwindcss
• @supabase/supabase-js
• @tanstack/react-query, react-hook-form, zod
• lucide-react-native

All of these work in both preview and on device. Adding any of them to your project does not require a special build — they’re already linked.

​

Packages to think twice about

Some packages are technically supported by Expo but bring a steep cost. Avoid unless you really need them: The AI in the chat will tell you if you ask for one of these, suggesting the alternative. You can override and continue, but expect a longer first build.

​

What an AI agent will and won’t do for you

The AI knows the difference between OTA and Build & Ship. When you ask it to add a feature:

• JS-only feature (“add a search bar to the items list”) — applies via OTA, no rebuild. AI says: “Published to preview. Refresh your phone.”
• Native-dep feature (“add camera-based receipt scanning”) — AI installs expo-camera, modifies the screen, and includes “this needs a Build & Ship — click the button on the Builds page” in its response.
• Forbidden combo (“add Stripe Native SDK”) — AI refuses or steers you to @stripe/stripe-react-native which Expo supports, and tells you the rebuild is required.

When the AI is wrong (it sometimes thinks a package is pure-JS when it ships native code), you’ll find out at build time. The decoded error usually points at the package — re-trigger with Fix with AI and it’ll switch course.

​

Detection in the editor

When you save a package.json with a new native dependency, the editor flashes a banner:

Native dependency added: expo-camera — this change needs a Build & Ship to reach devices. OTA Update will not deliver it.

That’s your prompt to plan the build. You can keep iterating in JS first (say, building the UI for the camera feature with placeholders), then click Build & Ship once the surrounding code is solid.

​

What’s next