Guarding native imports

A JS bundle can run on a binary that does not contain every native module the bundle mentions. That happens in three situations:

Situation	Missing modules
Expo Go, or a dev client built before a dependency was added	Anything not compiled into that binary
An OTA update on an older store build	Modules added after that build
The web export	Every native-only module

A static import at the top of a file runs when the file is first evaluated. If the package’s entry calls requireNativeModule and the module is missing, it throws during evaluation. Every file that imports it, directly or through other files, fails with it. If that chain reaches a route or the root layout, the app does not render. So native-only modules that are not guaranteed to exist are never imported at the top of a file. The codebase uses three guards.

Guard 1: dynamic import inside the function

Move the import into the function that needs it and wrap it in try/catch.

async function loadHealthConnect(): Promise<HealthConnectModule | null> {
  try {
    return (await import('react-native-health-connect')) as unknown as HealthConnectModule;
  } catch {
    return null;
  }
}

Callers treat null as “not available on this device” and return a safe default. Where it is used:

Module	File
`react-native-health-connect`	`features/health/lib/healthConnect.ts`
`@kingstinct/react-native-healthkit`	`features/health/lib/healthKit.ts`
`expo-background-task`	`features/health/lib/backgroundTask.ts`
`react-native-share`	`features/share-story/lib/instagramStory.ts`, `storyShare.ts`
`expo-navigation-bar`	`components/SystemNavigationBar.tsx`
`expo-image-manipulator`	`lib/media/shrinkImage.ts`, with guard 2 in front

The module’s types are still checked, because TypeScript resolves the dynamic import normally. Where the library’s own types are too broad, the file declares a narrow local interface for the functions it uses and casts through unknown, as the health providers do. No any is needed.

The component variant

A component cannot await. SystemNavigationBar loads its native component in an effect and renders nothing until it arrives:

export function SystemNavigationBar({ style }: { style: SystemNavigationBarStyle }) {
  const [NavigationBar, setNavigationBar] = useState<NavigationBarComponent | null>(null);

  useEffect(() => {
    let active = true;
    void loadNavigationBar().then((component) => {
      if (active) setNavigationBar(() => component);
    });
    return () => {
      active = false;
    };
  }, []);

  return NavigationBar ? <NavigationBar style={style} /> : null;
}

This one sits in the root layout, so an unguarded import here would stop the whole app from rendering on a binary without the module.

Guard 2: probe before importing

A try/catch around await import() is not always enough. Project notes record a production incident: a guarded dynamic import of expo-image-manipulator still closed the app on binaries without the module when it ran from a tap handler. The explanation recorded there is that Metro reports a throwing module factory as a fatal error when no other module is mid-load, so the rejection never reaches the catch. During startup the load is nested inside another module’s evaluation and the catch works, which is why the pattern looked safe. The fix is to ask whether the native module exists before touching the JS package:

import { requireOptionalNativeModule } from 'expo';

const NATIVE_MODULE_NAME = 'ExpoImageManipulator';

async function loadManipulator() {
  if (!requireOptionalNativeModule(NATIVE_MODULE_NAME)) {
    return null;
  }
  try {
    return await import('expo-image-manipulator');
  } catch {
    return null;
  }
}

requireOptionalNativeModule returns null for a missing module instead of throwing. When it does, the package is never imported. scripts/test-shrink-image-guard.cjs pins this behaviour. Its first test is named “a binary without the manipulator uploads the original and never loads the module”. Use this guard for any module that is loaded from a press handler, an effect or a timer, and that might be absent on a live binary.

For your own modules

The local Android module is loaded the same way, at module scope, because the probe itself is safe:

const native =
  Platform.OS === 'android'
    ? requireOptionalNativeModule<CardioNotificationModule>(NATIVE_MODULE_NAME)
    : null;

Every exported function in cardioNotification.ts then checks native before using it.

Guard 3: Metro shims

Some packages are imported statically in many files, and guarding each import is not practical. expo-widgets and @expo/ui/swift-ui are imported by the widget and Live Activity layouts, for example. metro.config.js resolves these to stand-in files:

const WEB_SHIMS = {
  'expo-glass-effect': 'expo-glass-effect.tsx',
  'expo-widgets': 'expo-widgets.ts',
  '@expo/ui/swift-ui': 'expo-ui-swift-ui.tsx',
  '@expo/ui/swift-ui/modifiers': 'expo-ui-swift-ui-modifiers.ts',
  'react-native-webview': 'react-native-webview.tsx',
  'expo-camera': 'expo-camera.tsx',
  'expo-media-library': 'expo-media-library.ts',
  'react-native-view-shot': 'react-native-view-shot.ts',
};

const EXPO_GO_SHIMS = ['expo-widgets'];

The resolver uses a shim when the platform is web, or when the environment variable EXPO_GO_SHIMS is 1 and the module is in the EXPO_GO_SHIMS list.

EXPO_GO_SHIMS=1 pnpm start

That starts a bundle where expo-widgets is inert, for running in Expo Go. The shim returns no-op widget and Live Activity handles and a null widgetsDirectory. Because the swap happens in Metro, TypeScript still type-checks against the real packages. A shim only has to export what the app imports. What each shim does:

Shim	Behaviour
`expo-widgets.ts`	`createWidget`, `createLiveActivity` and `addUserInteractionListener` return inert handles. `widgetsDirectory` is null
`expo-glass-effect.tsx`	`GlassView` renders a plain `View`. Both availability checks are exported, so the glass primitives take their fallback path
`expo-ui-swift-ui.tsx`, `expo-ui-swift-ui-modifiers.ts`	Stand-ins for the SwiftUI components and modifiers used by widget layouts
`react-native-webview.tsx`	Renders an `iframe`, so PDFs and embedded video still show on web
`expo-camera.tsx`	`CameraView` renders a `View`. Permission hooks resolve without a camera
`expo-media-library.ts`	Permission calls and `saveToLibraryAsync` resolve without saving
`react-native-view-shot.ts`	`captureRef` resolves without capturing

Guard 4: platform files and platform checks

For UI that has no equivalent on a platform, Expo Router platform extensions keep the import out of that platform’s bundle:

(tabs)/_layout.tsx imports expo-router/unstable-native-tabs.
(tabs)/_layout.web.tsx and (tabs)/_layout.android.tsx do not.

For logic, check Platform.OS before using a platform-specific API. getHealthProvider() returns null on web, and promptForAppUpdate() returns early on anything that is not iOS or Android.

Version gates

Sometimes the module exists on every binary but a native fix does not. The health prompt is the example. It compares the installed version before showing a permission screen that older Android binaries cannot display:

export function runtimeIsAtLeast(minimum: string): boolean {
  return isVersionAtLeast(Constants.expoConfig?.version, minimum);
}

isVersionAtLeast is in features/health/lib/runtime.ts and is reused by the app update prompt.

Choosing a guard

Case	Guard
A package used in one or two files, called from async code	Dynamic import in a loader function
The same, but it may run from a tap or effect on a binary without it	Probe with `requireOptionalNativeModule`, then dynamic import
A native component in a layout	Lazy load in an effect, render null until loaded
Your own Expo module	`requireOptionalNativeModule` at module scope
A package imported statically across many files, missing on web	Metro shim
A whole screen or layout with no equivalent on a platform	Platform file extension
A native fix that only newer binaries have	Version gate

Things that defeat a guard

Re-exporting the guarded module from a barrel file with a static export * from.
Importing a type with a plain import in a setup where it is not erased. Use import type.
Calling into the module at the top level of a file, outside any function.
Adding a second, unguarded import of the same package in another file.

Before shipping JS that touches a new native module over the air, search for every import of that package and confirm each one is guarded. See OTA updates.

Overview

Getting set up

Conventions

Backend architecture

Building backend modules

Backend security and access

Background work and delivery

Backend platform features

Backend operations

Backend packages

Data model

JSON shapes

Web app: basics

Web app: data and API

Web app: auth, organizations and billing

Web app: UI foundations

Web app: feature areas

Web app: quality and delivery

Trainee app: foundations

Trainee app: UI

Trainee app: workouts

Trainee app: nutrition

Trainee app: forms, content and tracking

Trainee app: device features

Trainee app: native, build and release

Messaging integrations

Platform integrations

External API and automation

Operations

Guarding native imports

Guard 1: dynamic import inside the function

The component variant

Guard 2: probe before importing

For your own modules

Guard 3: Metro shims

Guard 4: platform files and platform checks

Version gates

Choosing a guard

Things that defeat a guard

​Guard 1: dynamic import inside the function

​The component variant

​Guard 2: probe before importing

​For your own modules

​Guard 3: Metro shims

​Guard 4: platform files and platform checks

​Version gates

​Choosing a guard

​Things that defeat a guard

Guard 1: dynamic import inside the function

The component variant

Guard 2: probe before importing

For your own modules

Guard 3: Metro shims

Guard 4: platform files and platform checks

Version gates

Choosing a guard

Things that defeat a guard