Native Modules and Components

The spec is an ordinary TypeScript file that exports an interface extending TurboModule and, as its default export, the result of looking that module up in the registry. It is the single source of truth: Codegen parses it, TypeScript type-checks every call site against it, and the native implementations are forced to match it.

Three details carry more weight than their size suggests. The interface must be named Spec and the file must be named Native<Something>.ts or be pointed at explicitly by jsSrcsDir — Codegen discovers specs by convention, and a file it does not recognise silently generates nothing. getEnforcing<Spec> throws at first access if the native side never registered a module under that name, which turns a missing or misconfigured native implementation into an immediate, named error instead of an undefined method call somewhere deep in a component; TurboModuleRegistry.get<Spec> is the nullable variant, for a module that is genuinely optional on one platform. And the types Codegen accepts are a deliberately restricted subset — boolean, number, string, string-literal unions, arrays, object literals, Promise<T>, and callbacks — because every one of them has to map onto something expressible in Kotlin and Objective-C++. A TypeScript type Codegen cannot map fails the build rather than degrading at runtime.

Note also that the spec imports TurboModule and TurboModuleRegistry from the package root — react-native — not from a deep path inside it. Deep imports are not part of the Strict TypeScript API that React Native 0.87 publishes, and code relying on them can break on any minor upgrade; see TypeScript in React Native.

Codegen is driven by a codegenConfig block in the project’s (or library’s) package.json. It tells the build where the specs live and what to generate from them:

name becomes the name of the generated native library (the Gradle module and the iOS pod target); type is modules for Turbo Native Modules, components for Fabric Native Components, or all when a package ships both; jsSrcsDir is the directory Codegen scans for specs, relative to the package.json; and android.javaPackageName is the package the generated Java/Kotlin lands in. Codegen then runs automatically as part of each platform’s build — a Gradle task on Android, a script build phase (installed by pod install) on iOS — so there is no separate generation command to remember in normal development. npx react-native codegen runs it on demand when you want to inspect the output before building.

Codegen never writes into your source tree. Its output lands in the build directories — android/app/build/generated/source/codegen/ and ios/build/generated/ios/ — and is regenerated from the spec on every build, which is exactly why the JavaScript-facing types and the native signatures cannot drift apart. For HapticTap it produces:

Both are compile-time contracts. Rename tap in the spec without touching the native side and the Android build fails on an unimplemented abstract member while the iOS build fails on an unsatisfied protocol requirement — which is the entire point of the exercise.

The Kotlin module extends the generated spec class and does the actual work. getName() must return the exact string the JavaScript side passes to getEnforcing — that string is the registry key:

A module is only reachable once a ReactPackage advertises it. Under the New Architecture the package implements BaseReactPackage (or TurboReactPackage), which is what makes loading lazy: the registry asks getModule(name, context) for a module only when JavaScript first resolves that name, and getReactModuleInfoProvider() describes what the package can supply without instantiating anything.

The package is then added to the host’s package list in MainApplication.kt (alongside the autolinked ones), and the Kotlin language features used above — when expressions, object companions, nullable types — are covered in Kotlin for Android.

iOS needs two files, because Codegen emits an Objective-C protocol and Swift cannot conform to an Objective-C protocol directly. The idiomatic split is to write the real logic in Swift and keep a thin Objective-C file that conforms to the generated protocol and forwards into it. For how Swift, Objective-C and Objective-C coexist in one Xcode target in general — bridging headers, the generated -Swift.h header and @objc — see Mixing Swift, Objective-C and C++ in an App.

RCT_EXPORT_MODULE() with no argument derives the registry name from the class name — HapticTap, matching getEnforcing<Spec>('HapticTap'). getTurboModule: is what hands the runtime the Codegen-generated JSI binding class for this module; every Objective-C Turbo Module implements it, and it is boilerplate you copy rather than write. The `.mm` extension (rather than `.m`) is mandatory: the generated headers are C. The Swift reference and the Objective-C reference cover both languages, including the @objc/NS_SWIFT_NAME interop rules that make the bridging header above work.

On a project using the app template’s RCTAppDelegate, an app-local module in the ios/Places target is picked up automatically once the file is in the Xcode target. A module shipped as a library instead registers itself through the autolinking manifest — covered under packaging, below.

On the JavaScript side there is nothing module-specific left to do: the default export of the spec file is the typed module. `PlaceCard’s favourite toggle calls it directly, alongside the state update it already performed:

HapticTap.tap('light') is fully typed: passing 'soft' is a compile error, because HapticStyle is a string-literal union in the spec. The call is synchronous — it returns as soon as the native method has been invoked, with no promise to await — which is exactly what a JSI-backed void method buys and what the legacy bridge could never offer.

tap() is the simplest possible shape. Three richer shapes cover almost everything else a module needs:

Promises. A spec method typed Promise<T> becomes a method taking a promise pair on the native side — Promise on Android (resolve/reject), RCTPromiseResolveBlock/RCTPromiseRejectBlock on iOS. This is the right shape for anything asynchronous or fallible, because a rejection surfaces in JavaScript as a normal thrown error you can try/catch:

Events. For native-initiated notifications there is no JavaScript callback to hold; the module emits events and JavaScript subscribes. Declare addListener(eventName: string): void and removeListeners(count: number): void in the spec (Codegen requires both for an event-emitting module), emit with emitDeviceEvent from the Kotlin module or emitOnChange-style generated helpers, and subscribe in JavaScript through NativeEventEmitter. Places does not need this for haptics, but it is the shape a location-tracking or download-progress module would take.

Constants. A getConstants() method in the spec returns a value read once, synchronously, at module initialisation — suited to genuinely static facts (a platform SDK version, a device capability flag) and actively unsuitable for anything that can change while the app runs, since JavaScript will keep the first value forever. In practice a Promise-returning getter is the better default, and getConstants() is worth using only when a value must be available synchronously during the first render.

The spec is again TypeScript, and again drives Codegen. The prop types come from React Native’s own Codegen-aware type aliases (imported from the package root), because a prop has to be expressible in the shadow tree:

Two separate mechanisms appear here, and the distinction matters. Props are declarative state: they live in the shadow tree, are diffed on every commit, and flow one way into the view. Commands are imperative, one-shot instructions sent to a specific mounted view through a ref — Commands.animateToPlace(ref.current, lat, lon) — for things that are events rather than state, like starting an animation or scrolling to a position. Modelling "animate the camera" as a prop would mean re-triggering it on every unrelated re-render.

DirectEventHandler<T> declares an event the view bubbles up to the on<Name> prop; the payload type is a Readonly object literal, and on the native side it is emitted as a structured event rather than a callback invocation.

Android implements the component with a ViewManager that Codegen has generated an interface and a delegate for. The manager creates the view, applies each prop, and handles commands:

The manager is registered from the same ReactPackage as any Turbo Module, through createViewManagers().

iOS implements the component as a subclass of RCTViewComponentView, the Fabric-era base class that replaced the old RCTViewManager. Props arrive already typed, in a generated C++ props struct, through updateProps:oldProps::

Comparing next against oldProps before doing expensive work is the usual optimisation: updateProps: is called on every commit that touches this view, not only when a prop you care about actually changed. The trailing PlaceMapViewCls() C function is how Fabric’s component registry discovers the class by name.

A native module frequently needs something in the app’s native project too — a permission string in Info.plist, an AndroidManifest.xml entry, a Gradle dependency, an entitlement. In a Continuous Native Generation workflow, where ios/ and android/ are generated by npx expo prebuild rather than committed, editing those files by hand is pointless: the next prebuild discards the edit. A config plugin is the supported answer — a JavaScript function that receives the app config and returns a modified one, applied during prebuild:

Referencing it from app.config.ts’s `plugins array means the permission is reapplied on every prebuild, on every machine and every CI run, without anyone remembering to re-edit a generated file. A published Expo module conventionally ships its plugin as app.plugin.js at the package root so consumers can list the package name alone. Building and Publishing covers prebuild and the native-project lifecycle in full.