⬡ Dev Tools/2026-03-27Advanced

Rork Max × Expo Modules API: Building and Distributing Custom Native Modules

Learn how to design, implement, test, and publish custom native modules using the Expo Modules API. Extend Rork Max with platform-specific features using Swift and Kotlin.

Rork Max²²⁹ Expo Modules API Native Modules⁵ React Native²⁰⁹ Swift⁴⁸ Kotlin² npm Publishing

✦ Premium Article

Setup and context — Why Custom Native Modules Matter

Rork Max covers a remarkable range of app development needs through AI-powered code generation and the Expo ecosystem. However, when building production-grade applications, you'll inevitably encounter situations where existing libraries fall short.

Accessing proprietary hardware sensors, building high-performance bridges to specific OS APIs, or wrapping third-party SDKs — these scenarios demand writing native code directly. The Expo Modules API provides a modern, elegant solution to this challenge.

Compared to the legacy React Native Bridge, the Expo Modules API delivers significant improvements in type safety, performance, and developer experience. This guide walks you through the entire journey — from module design to npm publication — with practical, production-ready code examples.

Who this article is for:

Developers who have shipped (or are about to ship) a Rork Max app
React Native developers ready to dive into native platform extensions
Anyone wanting to publish reusable native modules as npm packages

Expo Modules API Architecture and Design Philosophy

How It Differs from the Legacy Bridge

The traditional React Native Bridge relied on JSON serialization for JavaScript-to-native communication. While flexible, this approach had fundamental limitations.

Legacy Bridge issues:

Performance overhead from asynchronous JSON serialization
No type safety (prone to runtime errors)
Different implementation patterns required for iOS and Android

Expo Modules API solutions:

Synchronous communication via JSI (JavaScript Interface) for better performance
Type-safe design that leverages native Swift/Kotlin types directly
Unified, declarative API across both platforms

// Legacy Bridge — asynchronous communication via JSON
// NativeModules.MyModule.doSomething(callback)
 
// Expo Modules API — synchronous JSI-based calls
import { requireNativeModule } from 'expo-modules-core';
const MyModule = requireNativeModule('MyModule');
const result = MyModule.doSomething(); // Synchronous result

Module Lifecycle

Modules built with the Expo Modules API follow this lifecycle:

Registration: Automatic module discovery via expo-module.config.json
Definition: Module definition by extending the Module class in Swift/Kotlin
Linking: Expo's autolinking integrates the module into native projects automatically
Runtime: Direct invocation from JavaScript through JSI

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Understand the Expo Modules API architecture and implement modules in Swift and Kotlin from scratch

✦Apply unit testing and E2E testing strategies for custom native modules

✦Master the workflow for publishing your module as an npm package for the community

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Project Setup

Scaffolding an Expo Module

Start by generating the module project structure:

# Create a new module from the Expo Modules template
npx create-expo-module my-native-sensor
 
# Generated directory structure
# my-native-sensor/
# ├── src/                    # TypeScript API
# │   ├── index.ts
# │   └── MyNativeSensor.types.ts
# ├── ios/                    # Swift implementation
# │   └── MyNativeSensorModule.swift
# ├── android/                # Kotlin implementation
# │   └── MyNativeSensorModule.kt
# ├── expo-module.config.json # Module configuration
# └── package.json

Configuring expo-module.config.json

This file serves as the module's entry point. Expo's autolinking system detects it and automates native project integration.

{
  "platforms": ["ios", "android"],
  "ios": {
    "modules": ["MyNativeSensorModule"]
  },
  "android": {
    "modules": ["expo.modules.mynativesensor.MyNativeSensorModule"]
  }
}

Implementing the Native Module in Swift (iOS)

Basic Structure

The Expo Modules API for Swift uses a declarative DSL (Domain Specific Language) that makes defining functions, properties, and events intuitive.

// ios/MyNativeSensorModule.swift
import ExpoModulesCore
import CoreMotion
 
public class MyNativeSensorModule: Module {
    private let motionManager = CMMotionManager()
    private var isTracking = false
 
    // Module definition
    public func definition() -> ModuleDefinition {
        // Module name (referenced from JavaScript)
        Name("MyNativeSensor")
 
        // Expose constants
        Constants([
            "isAccelerometerAvailable": motionManager.isAccelerometerAvailable,
            "isGyroAvailable": motionManager.isGyroAvailable
        ])
 
        // Event definitions (subscribe via addEventListener in JS)
        Events("onSensorUpdate", "onError")
 
        // Synchronous function: returns current sensor value immediately
        Function("getCurrentReading") { () -> [String: Double] in
            guard let data = self.motionManager.accelerometerData else {
                throw SensorError.notAvailable
            }
            return [
                "x": data.acceleration.x,
                "y": data.acceleration.y,
                "z": data.acceleration.z,
                "timestamp": data.timestamp
            ]
        }
 
        // Async function: start sensor tracking
        AsyncFunction("startTracking") { (interval: Double, promise: Promise) in
            guard self.motionManager.isAccelerometerAvailable else {
                promise.reject(SensorError.notAvailable)
                return
            }
 
            self.motionManager.accelerometerUpdateInterval = interval
            self.motionManager.startAccelerometerUpdates(
                to: .main
            ) { [weak self] data, error in
                guard let self = self, let data = data else {
                    if let error = error {
                        self?.sendEvent("onError", [
                            "message": error.localizedDescription
                        ])
                    }
                    return
                }
 
                self.sendEvent("onSensorUpdate", [
                    "x": data.acceleration.x,
                    "y": data.acceleration.y,
                    "z": data.acceleration.z,
                    "timestamp": data.timestamp
                ])
            }
 
            self.isTracking = true
            promise.resolve(true)
        }
 
        // Stop sensor tracking
        Function("stopTracking") { () -> Bool in
            self.motionManager.stopAccelerometerUpdates()
            self.isTracking = false
            return true
        }
 
        // Cleanup on module destruction
        OnDestroy {
            if self.isTracking {
                self.motionManager.stopAccelerometerUpdates()
            }
        }
    }
}
 
// Custom error type
enum SensorError: Error, CustomStringConvertible {
    case notAvailable
 
    var description: String {
        switch self {
        case .notAvailable:
            return "Accelerometer is not available on this device"
        }
    }
}

Implementing a View Module

To expose native UI components to JavaScript, use the View definition:

// ios/MyNativeSensorView.swift
import ExpoModulesCore
import UIKit
 
class MyNativeSensorView: ExpoView {
    private let gaugeView = UIView()
    private let label = UILabel()
 
    required init(appContext: AppContext? = nil) {
        super.init(appContext: appContext)
        setupUI()
    }
 
    private func setupUI() {
        label.textAlignment = .center
        label.font = .monospacedSystemFont(ofSize: 16, weight: .medium)
        addSubview(gaugeView)
        addSubview(label)
    }
 
    // Props passed from JavaScript
    var value: Double = 0 {
        didSet {
            label.text = String(format: "%.3f g", value)
            updateGauge()
        }
    }
 
    var color: UIColor = .systemBlue {
        didSet { gaugeView.backgroundColor = color }
    }
 
    private func updateGauge() {
        let normalized = min(abs(value) / 2.0, 1.0)
        gaugeView.frame = CGRect(
            x: 0, y: 0,
            width: bounds.width * normalized,
            height: bounds.height
        )
    }
}

Implementing the Native Module in Kotlin (Android)

Basic Structure

The Android implementation follows the same declarative API pattern. The nearly symmetrical code structure between Swift and Kotlin keeps the learning curve low.

// android/src/main/java/expo/modules/mynativesensor/MyNativeSensorModule.kt
package expo.modules.mynativesensor
 
import android.content.Context
import android.hardware.Sensor
import android.hardware.SensorEvent
import android.hardware.SensorEventListener
import android.hardware.SensorManager
import expo.modules.kotlin.modules.Module
import expo.modules.kotlin.modules.ModuleDefinition
import expo.modules.kotlin.Promise
 
class MyNativeSensorModule : Module(), SensorEventListener {
    private var sensorManager: SensorManager? = null
    private var accelerometer: Sensor? = null
    private var isTracking = false
 
    override fun definition() = ModuleDefinition {
        // Module name (must match iOS)
        Name("MyNativeSensor")
 
        // Constants
        Constants(
            "isAccelerometerAvailable" to (getAccelerometer() != null),
            "isGyroAvailable" to (getGyroscope() != null)
        )
 
        // Events
        Events("onSensorUpdate", "onError")
 
        // Synchronous function
        Function("getCurrentReading") {
            // On Android, real-time sensor values can't be
            // fetched directly — return the last cached reading
            lastReading ?: mapOf(
                "x" to 0.0,
                "y" to 0.0,
                "z" to 0.0,
                "timestamp" to System.currentTimeMillis().toDouble()
            )
        }
 
        // Async function
        AsyncFunction("startTracking") { interval: Double, promise: Promise ->
            val manager = getSensorManager()
            val sensor = getAccelerometer()
 
            if (sensor == null) {
                promise.reject(
                    "SENSOR_UNAVAILABLE",
                    "Accelerometer is not available",
                    null
                )
                return@AsyncFunction
            }
 
            val delayMicros = (interval * 1_000_000).toInt()
            manager?.registerListener(
                this@MyNativeSensorModule,
                sensor,
                delayMicros
            )
            isTracking = true
            promise.resolve(true)
        }
 
        // Stop function
        Function("stopTracking") {
            sensorManager?.unregisterListener(this@MyNativeSensorModule)
            isTracking = false
            true
        }
 
        // Cleanup
        OnDestroy {
            if (isTracking) {
                sensorManager?.unregisterListener(
                    this@MyNativeSensorModule
                )
            }
        }
    }
 
    // Cache the last sensor reading
    private var lastReading: Map<String, Double>? = null
 
    override fun onSensorChanged(event: SensorEvent?) {
        event?.let {
            val reading = mapOf(
                "x" to it.values[0].toDouble(),
                "y" to it.values[1].toDouble(),
                "z" to it.values[2].toDouble(),
                "timestamp" to (it.timestamp / 1_000_000.0)
            )
            lastReading = reading
            sendEvent("onSensorUpdate", reading)
        }
    }
 
    override fun onAccuracyChanged(sensor: Sensor?, accuracy: Int) {}
 
    private fun getSensorManager(): SensorManager? {
        if (sensorManager == null) {
            sensorManager = appContext.reactContext
                ?.getSystemService(Context.SENSOR_SERVICE)
                as? SensorManager
        }
        return sensorManager
    }
 
    private fun getAccelerometer(): Sensor? {
        if (accelerometer == null) {
            accelerometer = getSensorManager()
                ?.getDefaultSensor(Sensor.TYPE_ACCELEROMETER)
        }
        return accelerometer
    }
 
    private fun getGyroscope(): Sensor? {
        return getSensorManager()
            ?.getDefaultSensor(Sensor.TYPE_GYROSCOPE)
    }
}

Designing the TypeScript API Layer

Type Definitions

Strict TypeScript type definitions for the native module ensure type safety on the JavaScript side.

// src/MyNativeSensor.types.ts
 
export interface SensorReading {
  x: number;
  y: number;
  z: number;
  timestamp: number;
}
 
export interface SensorError {
  message: string;
}
 
export interface MyNativeSensorModule {
  // Constants
  isAccelerometerAvailable: boolean;
  isGyroAvailable: boolean;
 
  // Functions
  getCurrentReading(): SensorReading;
  startTracking(interval: number): Promise<boolean>;
  stopTracking(): boolean;
}
 
export type SensorEventPayload = SensorReading;

Module Exports

// src/index.ts
import {
  requireNativeModule,
  EventEmitter,
  Subscription,
} from 'expo-modules-core';
import type {
  MyNativeSensorModule,
  SensorReading,
  SensorError,
} from './MyNativeSensor.types';
 
// Get the native module
const NativeModule =
  requireNativeModule<MyNativeSensorModule>('MyNativeSensor');
 
// Event emitter
const emitter = new EventEmitter(NativeModule);
 
// --- Public API ---
 
/** Whether the accelerometer is available */
export const isAccelerometerAvailable: boolean =
  NativeModule.isAccelerometerAvailable;
 
/** Whether the gyroscope is available */
export const isGyroAvailable: boolean =
  NativeModule.isGyroAvailable;
 
/** Get the current sensor reading synchronously */
export function getCurrentReading(): SensorReading {
  return NativeModule.getCurrentReading();
}
 
/**
 * Start sensor tracking
 * @param interval - Update interval in seconds. Default: 0.1 (100ms)
 */
export async function startTracking(
  interval: number = 0.1
): Promise<boolean> {
  return NativeModule.startTracking(interval);
}
 
/** Stop sensor tracking */
export function stopTracking(): boolean {
  return NativeModule.stopTracking();
}
 
/** Subscribe to sensor update events */
export function addSensorListener(
  callback: (data: SensorReading) => void
): Subscription {
  return emitter.addListener('onSensorUpdate', callback);
}
 
/** Subscribe to error events */
export function addErrorListener(
  callback: (error: SensorError) => void
): Subscription {
  return emitter.addListener('onError', callback);
}

Integrating with a Rork Max App

Let's see how to integrate the module you've built into a Rork Max project.

Local Module Integration

During development, referencing via a local path is most efficient:

// package.json (in your Rork Max project)
{
  "dependencies": {
    "my-native-sensor": "file:./modules/my-native-sensor"
  }
}

Custom React Hook Wrapper

In production app code, wrapping the module in a custom hook is the recommended pattern:

// hooks/useNativeSensor.ts
import { useEffect, useRef, useState, useCallback } from 'react';
import {
  startTracking,
  stopTracking,
  addSensorListener,
  addErrorListener,
  isAccelerometerAvailable,
} from 'my-native-sensor';
import type { SensorReading } from 'my-native-sensor';
 
interface UseSensorOptions {
  interval?: number;
  autoStart?: boolean;
}
 
interface UseSensorReturn {
  reading: SensorReading | null;
  isTracking: boolean;
  isAvailable: boolean;
  start: () => Promise<void>;
  stop: () => void;
  error: string | null;
}
 
export function useNativeSensor(
  options: UseSensorOptions = {}
): UseSensorReturn {
  const { interval = 0.1, autoStart = false } = options;
  const [reading, setReading] = useState<SensorReading | null>(null);
  const [isActive, setIsActive] = useState(false);
  const [error, setError] = useState<string | null>(null);
  const subscriptionRef = useRef<ReturnType<
    typeof addSensorListener
  > | null>(null);
 
  const start = useCallback(async () => {
    if (!isAccelerometerAvailable) {
      setError('Sensor not available on this device');
      return;
    }
    try {
      // Register event listener
      subscriptionRef.current = addSensorListener((data) => {
        setReading(data);
      });
      await startTracking(interval);
      setIsActive(true);
      setError(null);
    } catch (e) {
      setError(e instanceof Error ? e.message : 'Unknown error');
    }
  }, [interval]);
 
  const stop = useCallback(() => {
    stopTracking();
    subscriptionRef.current?.remove();
    subscriptionRef.current = null;
    setIsActive(false);
  }, []);
 
  // autoStart support
  useEffect(() => {
    if (autoStart) {
      start();
    }
    return () => {
      stop();
    };
  }, [autoStart, start, stop]);
 
  return {
    reading,
    isTracking: isActive,
    isAvailable: isAccelerometerAvailable,
    start,
    stop,
    error,
  };
}

Usage in an App Component

// screens/SensorDashboard.tsx
import React from 'react';
import { View, Text, Pressable, StyleSheet } from 'react-native';
import { useNativeSensor } from '../hooks/useNativeSensor';
 
export default function SensorDashboard() {
  const { reading, isTracking, isAvailable, start, stop, error } =
    useNativeSensor({ interval: 0.05 });
 
  if (!isAvailable) {
    return (
      <View style={styles.container}>
        <Text style={styles.errorText}>
          Accelerometer is not available on this device
        </Text>
      </View>
    );
  }
 
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Sensor Dashboard</Text>
 
      {reading && (
        <View style={styles.readingContainer}>
          <Text style={styles.axis}>X: {reading.x.toFixed(4)}</Text>
          <Text style={styles.axis}>Y: {reading.y.toFixed(4)}</Text>
          <Text style={styles.axis}>Z: {reading.z.toFixed(4)}</Text>
        </View>
      )}
 
      {error && <Text style={styles.errorText}>{error}</Text>}
 
      <Pressable
        style={[styles.button, isTracking && styles.buttonActive]}
        onPress={isTracking ? stop : start}
      >
        <Text style={styles.buttonText}>
          {isTracking ? 'Stop' : 'Start'} Tracking
        </Text>
      </Pressable>
    </View>
  );
}
 
// Expected output:
// ┌─────────────────────────┐
// │     Sensor Dashboard     │
// │                          │
// │   X: 0.0023             │
// │   Y: -0.9812            │
// │   Z: 0.0145             │
// │                          │
// │   [Start Tracking]       │
// └─────────────────────────┘
 
const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: 'center', padding: 24 },
  title: { fontSize: 24, fontWeight: 'bold', marginBottom: 24 },
  readingContainer: { marginBottom: 24 },
  axis: { fontSize: 18, fontFamily: 'monospace', marginVertical: 4 },
  button: {
    backgroundColor: '#007AFF',
    padding: 16,
    borderRadius: 12,
    alignItems: 'center',
  },
  buttonActive: { backgroundColor: '#FF3B30' },
  buttonText: { color: '#fff', fontSize: 16, fontWeight: '600' },
  errorText: { color: '#FF3B30', marginBottom: 16 },
});

Testing Strategy

Unit Tests (TypeScript Layer)

// __tests__/MyNativeSensor.test.ts
import {
  getCurrentReading,
  startTracking,
  stopTracking,
} from '../src/index';
 
// Mock Expo Modules
jest.mock('expo-modules-core', () => ({
  requireNativeModule: () => ({
    isAccelerometerAvailable: true,
    isGyroAvailable: true,
    getCurrentReading: jest.fn(() => ({
      x: 0.01,
      y: -0.98,
      z: 0.02,
      timestamp: Date.now(),
    })),
    startTracking: jest.fn(() => Promise.resolve(true)),
    stopTracking: jest.fn(() => true),
  }),
  EventEmitter: jest.fn(() => ({
    addListener: jest.fn(),
  })),
}));
 
describe('MyNativeSensor', () => {
  it('getCurrentReading returns valid sensor data', () => {
    const reading = getCurrentReading();
    expect(reading).toHaveProperty('x');
    expect(reading).toHaveProperty('y');
    expect(reading).toHaveProperty('z');
    expect(typeof reading.x).toBe('number');
  });
 
  it('startTracking resolves with true', async () => {
    const result = await startTracking(0.1);
    expect(result).toBe(true);
  });
 
  it('stopTracking returns true', () => {
    const result = stopTracking();
    expect(result).toBe(true);
  });
});
 
// Expected output:
// PASS  __tests__/MyNativeSensor.test.ts
//   MyNativeSensor
//     ✓ getCurrentReading returns valid sensor data (3 ms)
//     ✓ startTracking resolves with true (1 ms)
//     ✓ stopTracking returns true (1 ms)

Native-Side Tests (Swift XCTest)

// ios/Tests/MyNativeSensorTests.swift
import XCTest
@testable import MyNativeSensor
import ExpoModulesCore
 
final class MyNativeSensorTests: XCTestCase {
    var module: MyNativeSensorModule!
 
    override func setUp() {
        super.setUp()
        module = MyNativeSensorModule()
    }
 
    func testModuleNameIsCorrect() {
        // Verify Name() is set correctly in definition()
        let definition = module.definition()
        XCTAssertNotNil(definition)
    }
 
    func testStopTrackingReturnsFalseWhenNotStarted() {
        // Verify stopping is safe when tracking hasn't started
        let result = module.definition()
        XCTAssertNotNil(result)
    }
}

Publishing as an npm Package

Preparing package.json

{
  "name": "@your-scope/my-native-sensor",
  "version": "1.0.0",
  "description": "Custom accelerometer module for Expo/React Native",
  "main": "build/index.js",
  "types": "build/index.d.ts",
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build",
    "test": "jest"
  },
  "peerDependencies": {
    "expo": ">=52.0.0",
    "react": ">=18.0.0",
    "react-native": ">=0.76.0"
  },
  "devDependencies": {
    "expo-modules-core": "^2.0.0",
    "typescript": "^5.0.0"
  },
  "files": [
    "build/",
    "ios/",
    "android/",
    "expo-module.config.json",
    "src/"
  ],
  "keywords": [
    "expo",
    "react-native",
    "sensor",
    "accelerometer",
    "native-module"
  ],
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org/my-native-sensor"
  },
  "license": "MIT"
}

Publishing Steps

# 1. Compile TypeScript
npm run build
 
# 2. Dry run (verify contents without actually publishing)
npm pack --dry-run
# Output: lists all files that would be included
 
# 3. Log in to npm
npm login
 
# 4. Publish (scoped packages require --access public)
npm publish --access public
 
# Expected output:
# npm notice Publishing to https://registry.npmjs.org/ with tag latest
# + @your-scope/my-native-sensor@1.0.0

Versioning Best Practices

It's important to clearly communicate Expo SDK compatibility in your module's versioning:

v1.0.x — Expo SDK 52 support
v1.1.x — Expo SDK 53 support (backward compatible)
v2.0.x — Expo SDK 54 support (breaking changes)

Including a support matrix in your README makes life much easier for users.

Performance Optimization Tips

Here are techniques to get the most out of your custom native modules.

Controlling Event Frequency

For modules that fire events at high frequency (like sensor data), implement throttling to prevent JavaScript thread congestion:

// iOS: Throttle events to a minimum interval
private var lastEventTime: TimeInterval = 0
private let minInterval: TimeInterval = 0.016 // ~60fps
 
private func throttledSendEvent(_ data: [String: Any]) {
    let now = CACurrentMediaTime()
    guard now - lastEventTime >= minInterval else { return }
    lastEventTime = now
    sendEvent("onSensorUpdate", data)
}

Preventing Memory Leaks

Always implement the OnDestroy handler in your native modules to release listeners and timers. Neglecting this causes memory leaks during app background transitions.

Summary

Building custom native modules with the Expo Modules API dramatically expands what's possible with Rork Max. Thanks to the declarative API design, you can write Swift and Kotlin implementations using unified patterns, improving maintainability across platforms.

The sensor module pattern demonstrated in this guide applies to any native extension — camera controls, Bluetooth communication, OS-specific UI components, and more. Give it a try in your own projects.

For a deeper understanding of the React Native and Expo architecture, check out React Native 0.84 + Hermes V1 Complete Guide and Deep Dive into Rork's React Native + Expo Architecture.

Thank You for Reading

Rork Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.