Expo Modules API

Expo Modules API

Purpose

The Expo Modules API is the recommended way to build native modules for Expo and React Native. It sits on JSI and exposes a declarative DSL in Swift and Kotlin so one module definition stays consistent across iOS and Android.

Use this skill whenever someone is building, extending, or debugging a module — not only when they mention "Module API" by name. Typical work: new expo-* package, app-local module in modules/, adding native methods to an existing module, or shipping a native view to React.

Read order: workflows below → REFERENCE.md for every DSL component → EXAMPLES.md for copy-paste starters.

When to use

Official doc index: llms.txt. Getting started: Expo Modules — Get Started.

What you are building

A standard Expo module usually contains:

my-module/
├── expo-module.config.json    # module metadata for autolinking
├── src/index.ts               # JS/TS public API (requireNativeModule)
├── ios/MyModule.swift         # class MyModule: Module
├── android/.../MyModule.kt    # class MyModule : Module()
└── (optional) src/MyView.tsx  # requireNativeViewManager wrapper

Core rule: every exported native capability is declared inside definition() -> ModuleDefinition { ... }. JavaScript reaches it via requireNativeModule('Name') or requireNativeViewManager('ViewName') — names must match Name("...") in native code.

Module types (pick a shape)

Building a headless module (step-by-step)

1. Scaffold

• Prefer npx create-expo-module@latest my-module for publishable packages.
• For monorepos, follow Expo monorepo / local modules docs; ensure expo-module.config.json exists and the app depends on the package.

2. Native module class

Swift — public class MyModule: Module with public func definition() -> ModuleDefinition.

Kotlin — class MyModule : Module() with override fun definition() = ModuleDefinition { }.

3. Declare the JS name

Name("MyModule")

Name("MyModule")

This string is what requireNativeModule('MyModule') uses.

4. Export behavior

Threading default: Function runs on the JavaScript thread and blocks the app until it returns. AsyncFunction returns a Promise and runs off the JS thread by default — use it for network, disk, long CPU, and most native SDK calls.

5. TypeScript public API

import { requireNativeModule } from 'expo-modules-core';

const Native = requireNativeModule('MyModule');

export async function doWork(input: string): Promise<string> {
  return Native.doWorkAsync(input);
}

Type event modules with NativeModule<Events> (see EXAMPLES.md).

6. Verify

• Rebuild native (npx expo run:ios / run:android or dev client).
• Call each export from JS; confirm Promise vs sync behavior.
• If listeners use battery/CPU, wire OnStartObserving / OnStopObserving.

Building a native view module (step-by-step)

1. Native view class

• Android: must extend ExpoView(context, appContext).
• iOS: extend ExpoView (extends RCTView) for appContext and style/accessibility helpers.

Do not change constructor parameters — expo-modules-core constructs the view.

2. Register in definition()

View(MyView.self) {
  Name("MyView")           // optional but recommended
  Prop("color") { view, color in ... }
  Events("onPress")
  AsyncFunction("focus") { view in view.becomeFirstResponder() }
}

3. View events

In the view class, declare EventDispatcher properties with the same names as in Events("onPress"):

class MyView: ExpoView {
  let
}

Invoke onPress(["key": value]) from native; JS receives event.nativeEvent.

4. React usage

const NativeView = requireNativeViewManager('MyView');
<NativeView => {}} ref={ref} />
// ref.current?.focus() for view AsyncFunctions

View AsyncFunction runs on the main/UI queue; first parameter is always the view instance.

Quick decisions

Argument typing (module builders)

Prefer typed bridges over raw maps:

1. Primitives — String, Int, Bool, arrays, maps.
2. Record — JS objects with @Field defaults (best for options bags).
3. Enumerable enums — closed sets (encoding, quality, etc.).
4. Either — one of 2–4 types for overloaded JS args.
5. Built-in convertibles — URL, UIColor/Color, CGPoint, Uri, files — see REFERENCE.md#built-in-convertibles.
6. Convertible / ModuleConverters — domain types (iOS/Android).
7. JavaScriptValue — escape hatch; sync + JS thread only.

Platform lifecycle (summary)

Use lifecycle hooks instead of constructors when work depends on React or Activity being ready.

Full Module DSL list: REFERENCE.md#lifecycle.

Android Package lifecycle listeners (when building modules)

Some Android hooks cannot be done only inside ModuleDefinition — especially early Activity.onCreate, custom onBackPressed, or Application.onCreate without asking users to paste code into MainActivity.java / MainApplication.java.

For those cases, implement Expo’s Package + listener pattern (official guide):

Choose Module DSL vs Package listener:

Not supported on ReactActivityLifecycleListener: onStart, onStop (hooks come from ReactActivityDelegate, not MainActivity).

Maintenance: listener interfaces may change between SDKs — override only methods you need; do not implement every method.

Detail: REFERENCE.md#android-lifecycle-listeners. Full deep-link bridge: EXAMPLES.md#android-lifecycle-to-js.

Common mistakes when building modules

Review checklist (before shipping a module)

• Name matches JS requireNativeModule / view manager
• No blocking Function for I/O, network, or disk
• AsyncFunction for promises; coroutines on Android where appropriate
• Records/enums for non-trivial JS objects
• Events + start/stop observing if native listeners cost resources
• View: ExpoView, EventDispatcher for callbacks, ref methods on main queue
• TypeScript types for public API and events
• Tested on both iOS and Android (lifecycle differs)
• No deprecated Constants (use Constant)
• Android: Package listeners registered if needed; expo-module.config.json lists module class
• Lifecycle → JS bridge uses observers + WeakReference; listeners removed in OnStopObserving

Operating modes

Authoring mode

1. Confirm module shape (headless / view / hybrid).
2. Implement definition() on both platforms with matching Name and method names.
3. Add TS wrapper in src/index.ts.
4. Rebuild native and run smoke tests from JS.

Debug mode

1. Verify Name and autolinking.
2. Classify call as sync vs async and check thread.
3. For events, trace Events → observer setup → sendEvent / EventDispatcher.
4. Compare with EXAMPLES.md and reference modules (expo-clipboard, expo-image-picker).

Additional resources

• REFERENCE.md — complete DSL, argument types, guides
• EXAMPLES.md — end-to-end patterns for module authors
• REFERENCE.md#android-lifecycle-listeners — Activity/Application hooks without MainActivity edits
• Reference implementations: expo-linking, expo-clipboard, expo-crypto, expo-image-picker, expo-linear-gradient, expo-web-browser in expo/expo packages